FEATURE: GPS-based real-time lap delta (gap to reference lap)

[FabioRoss]

What problem are you trying to solve?

When karting or circuit racing, the most useful number on a live display is not
your current lap time — it's whether you are gaining or losing time compared to
your personal best. "Am I +0.4s slower through the first sector?" tells you
exactly where you're losing it.

DovesLapTimer already tracks the best lap time. The missing piece is comparing
WHERE you are on track right now (GPS position + elapsed time) against WHERE
you were at the same track position during the best lap, and giving the user
a signed delta in seconds: positive = currently slower, negative = currently faster.

Without this, users have to maintain a separate GPS trace buffer and correlation
logic in their sketch, duplicating the lap vector infrastructure the library
already needs internally.

Proposed solution

Add a GPS-position-based lap delta calculation as a first-class feature inside
DovesLapTimer. The library already records lat/lng every fix — we need to:

1. Store each GPS fix during the current lap as a LapPoint:

   struct LapPoint {
   unsigned long time; // ms from lap start
   double posX; // latitude
   double posY; // longitude
   int32_t speed; // reserved for future use
   };

2. On new best lap: auto-promote currentLapVector → referenceLapVector.

3. On every subsequent GPS fix: find the nearest reference point and compute:
   rawDelta = currentLapTime - referenceTimeAtNearestPoint

4. Apply an Exponential Moving Average filter to smooth GPS noise:
   filteredDelta = alpha * filteredDelta + (1 - alpha) * rawDelta
   (default alpha = 0.3f; user-configurable)

5. Apply a ±120s sanity guard — reject physically impossible values without
   corrupting the EMA state (no update on reject, not zeroing).

6. Throttle updates to 25 Hz (every 40ms) to match typical GPS output rate
   and avoid spinning on high-update microcontrollers.

7. Expose public API:
   float getDelta() const; // filtered delta, seconds
   void setFilterAlpha(float alpha); // EMA smoothing factor
   float getFilterAlpha() const;
   void setUseNewDeltaCalc(bool use); // algorithm selector
   bool getUseNewDeltaCalc() const;
   const std::vector& getReferenceLapVector() const; // for SD save/load
   void setReferenceLapVector(const std::vector&); // for SD restore

TWO SEARCH ALGORITHMS (user-selectable):

Algorithm A — Full scan (simple, good for static reference):
For each fix: scan ALL reference points, return nearest by haversine.
O(n) per update. Fine for short tracks or infrequent GPS rates.

Algorithm B — Windowed search (default recommended):
Maintain lastBestIdx from previous match. Search only a bounded window:
- LOOK_BACK = 125 frames (~5s at 25 Hz) — handles driver gaining time fast
- LOOK_FORWARD = 375 frames (~15s at 25 Hz) — handles driver losing time badly
O(1) amortized. Eliminates hairpin jitter where the full-scan jumps to the
"wrong" nearest point on the opposite side of a u-turn.

Internal state reset on lap start:
currentDelta = 0; filteredDelta = 0; lastBestIdx = 0;

===============================================================================
REAL-WORLD VALIDATION

This exact implementation has been running in a real karting datalogger (RaceBoard)
for multiple race sessions at Italian circuits. Development went through three
significant evolution commits:

• Initial implementation: identified hairpin jitter with full-scan algorithm
• Windowed search fix: bounded ±5s/±15s window eliminated jitter at hairpins
• Sanity guard fix: original ±5s clamp caused delta to freeze during aggressive
  sector improvements >5s; replaced with ±120s guard that preserves EMA state

The filtered delta has been validated as smooth and physically meaningful on
track. Race displays update correctly through sector changes, hairpins, and
chicanes without jumps.

===============================================================================
CONTRIBUTION READINESS

Code exists and is working. For a PR:

• Strip SD logger and circuit-database dependencies (those are RaceBoard-specific)
• Update loop() call sites to upstream's current signature
• Add regression test: synthetic reference lap + synthetic current lap with
  known position/time offset → verify getDelta() converges to expected value
• Add unit test: EMA filter state NOT corrupted when rawDelta > ±120s
• Add unit test: windowed algorithm correctly handles driver gaining/losing time
• Doxygen comments on all new public methods
• Consider: should reference lap auto-save/load be part of this PR or a
  follow-on? (See also Issue [NEEDS MORE DISCUSSION] FEATURE: Session-persistent lap state injection (setLapsData) #34 Session Persistence)

Memory note: std::vector on a 125-point lap at 25 Hz costs ~
125 * sizeof(LapPoint) = ~2.5 KB RAM per vector (two vectors = ~5 KB).
This is acceptable on ESP32/nRF52 targets; may need opt-out on AVR Mega.

Alternatives considered

1. Pace difference (getPaceDifference) — already exists in the library but
   uses distance/time pace ratio, not position correlation. This doesn't
   tell you WHERE on track you are gaining/losing; it's a trailing average.

2. User manages their own GPS trace vector externally — current workaround.
   Forces every user who wants delta to reinvent the same infrastructure.
   The library already has the GPS fixes; duplicating in user code is wasteful.

3. Sector-based delta only (see companion issue FEATURE: Per-sector delta timing (vs best and optimal) with live lap progress delta #31) — sector deltas tell you
   per-split performance but only update at line crossings, not continuously.
   GPS delta updates every fix, giving live feedback through corners.

[TheAngryRaven]

Love this one — live position-correlated delta is the single most useful number on a race display, and you're right that getPaceDifference() can't do it (it's just a trailing distance/time ratio, it can't tell you where you're losing time). This belongs in the core library, not user sketches.

A few changes before you start coding so the PR lands clean with the library's constraints:

1. Ring buffer, not std::vector (this is the big one).
The library targets down to AVR Mega and has a hard rule: no heap allocation in the GPS hot path. There's currently zero std::vector/new/malloc anywhere in src/ — everything is fixed buffers. A growing vector with push_back every fix would allocate on the hot path and cost ~5 KB across two vectors, which blows the AVR budget.

Instead, mirror the existing crossingPointBuffer pattern: a fixed-capacity ring buffer, sized per platform with the same #if defined(RAMEND) && defined(RAMSTART) gate (small on classic AVR, 100+ on nRF52/ESP32). Promote-to-reference becomes a memcpy of the current buffer into the reference buffer — no allocation. Keep LapPoint as you have it (drop int32_t speed unless something uses it now — "reserved for future use" is dead weight).

2. Windowed search only — drop the algorithm selector.
You already said the windowed ±5s/±15s search is the recommended default and that full-scan jitters at hairpins. So just ship the windowed one. Please drop the full-scan path and setUseNewDeltaCalc()/getUseNewDeltaCalc() entirely — a config flag selecting between "the good one" and "the one with known jitter" is just surface area to maintain (and "new" in an API name rots fast).

3. API naming, massaged to match the rest of the library:

• getDelta() → getLapDelta() (everything else is getXxxLapXxx)
• Keep setFilterAlpha() / getFilterAlpha() as-is — good.
• Reference-lap accessors: don't return std::vector&. Expose them as const LapPoint* getReferenceLap(uint16_t& outCount) const + a setReferenceLap(const LapPoint*, uint16_t count). That's all an SD save/load needs, and it keeps the no-std::vector contract.
• Drop the SD auto-save/load from this PR — persistence is logger-side, track it under [NEEDS MORE DISCUSSION] FEATURE: Session-persistent lap state injection (setLapsData) #34. The accessors above are the only hook the library needs to provide.

4. Keep these exactly as proposed — they're spot on: EMA smoothing (alpha default 0.3, user-configurable), the ±120s sanity guard that skips the update rather than zeroing (preserves EMA state), the 25 Hz throttle, and the currentDelta/filteredDelta/lastBestIdx reset on lap start.

5. Tests + docs are required to merge (see CLAUDE.md / CONTRIBUTING):

• Layer-2 unit test: synthetic reference lap + synthetic current lap with a known time offset → getLapDelta() converges to expected.
• Layer-2: EMA state is NOT corrupted when rawDelta > ±120s (skip, don't zero).
• Layer-2: windowed search handles both gaining and losing time across the window bounds.
• Bonus: confirm it stays sane against the Layer-3 NMEA replay fixtures.
• Doxygen @brief/@param/@return on every new public method, a ## [Unreleased] CHANGELOG entry, and a README mention.
• One logical change per PR — just the delta feature, branch off master.

The EMA/guard/throttle/windowed-search logic you've already validated on track is the hard part and it's all good to keep — the asks above are basically "fixed buffer instead of vector" + trimming one redundant code path. Ping me if the ring-buffer sizing macro is unfamiliar and I'll point you at the crossingPointBuffer block to copy from.

---

Generated by Claude Code

[FabioRoss]

Just a few clarifications before i start coding:

1- i understand the memory constraints but i'm not sure this is a feature meant for lower memory boards, especially with 25hz updates from gnss (a 40 seconds lap ideally would need 1000-1200 slots buffer). I don't think we can use a ring buffer and overwrite it during the course of a lap, as you need to save the entire current lap until you cross the line, at which point you decide if to exchange the previous best with it or discard it.

1b- speed is for lap analysis via web tool, i can drop it if you prefer

2- windowed search (should) work great and be the preferred method, but i didn't conduct extensive real world tests on it, therefore either i wait on the implementation or i proceed and hand over the furter tests task

3- fair, let's keep this issue constrained to the feature pertinence

5- alright, i'll check docs and ask if have doubts

let me know 👍

[TheAngryRaven]

@FabioRoss you're right on point #1 and it changes the plan — scrap my ring-buffer suggestion. A ring buffer works for crossingPointBuffer because that only needs the few fixes around a line crossing. This feature has to retain the entire current lap until the finish line, since that's where you decide promote-or-discard. That's whole-lap recording, not a sliding window. My analogy was wrong.

Here's the corrected plan (supersedes my line-by-line above):

This is a non-AVR feature, gated at compile time

Honest math: LapPoint at 24 bytes x ~1000-1200 points/lap x 2 buffers ≈ ~57 KB. Mega has 8 KB total SRAM — no allocation strategy (ring, malloc, anything) fits that, because the algorithm inherently needs the whole lap. So:

• Gate the whole feature behind #define DOVES_ENABLE_LAP_DELTA, auto-disabled on AVR via the existing #if defined(RAMEND) && defined(RAMSTART) detector. The core library still compiles and runs on Mega — Mega just doesn't get live delta.
• No malloc. Use static fixed buffers. A one-time init malloc wouldn't technically break the hot-path rule, but the only thing it buys over a static array is "pay RAM only when enabled," and the compile-time #define already gives you that while keeping the clean "zero heap in src/" property. So we don't spend the exception.
• Promote-on-best-lap = double-buffer with a pointer swap (current/reference are two static buffers + a pointer), so promotion is O(1), not a 28 KB memcpy.

Distance-based sampling instead of 25 Hz time sampling (the important one)

Store one point per N meters of travel, not per GPS fix. This is the key change and it's strictly better here:

• Decouples the buffer from both GPS rate and lap duration. A 25 Hz and an 18 Hz module produce the same reference at the same sample distance; a slow lap doesn't bloat it. Memory is bounded by track length alone (max lap length ≈ MAX_LAP_POINTS x sampleMeters).
• Runtime-tunable setDeltaSampleMeters(float) with a per-platform default (#define DOVES_DELTA_SAMPLE_METERS_DEFAULT), plus compile-time MAX_LAP_POINTS.
• Overflow behavior must be defined: if a lap exceeds capacity at the configured spacing, refuse to promote that lap and raise a deltaBufferOverflow flag — never silently truncate, that corrupts delta for the back half of the lap. Document the capacity relationship next to the setter.
• Drop speed (your 1b) — it's lap-analysis/web-tool data, i.e. logger-side, not timing. Keeps LapPoint lean.

Accuracy — why the lower point count doesn't cost you

Splitting this because the two halves behave very differently:

• Lap/sector times: unaffected. The delta buffer is a separate subsystem; official times still come from the line-crossing interpolation (the ±50 ms golden-tested path). Sparse sampling never touches a recorded time.
• The delta readout: error comes from your current position landing between two stored points. The fix is to interpolate between the two bracketing reference points (project current position onto the segment, lerp their timestamps) rather than snap-to-nearest. That nearly eliminates quantization error. What remains is chord error on curves, ≈ spacing²/(8R) — at 5 m spacing that's ~0.4 m lateral on a tight hairpin, centimeters on a sweeper.
• You're not discarding real precision: GPS noise is ~1-2.5 m CEP on these modules. Below ~2-3 m spacing you're sampling jitter, not signal — so 3-5 m sampling sits near the sensor's own noise floor and finer wouldn't help even with infinite RAM.
• The EMA (alpha 0.3) mops up whatever high-frequency residual survives, and since the reference is recorded once (your promoted best lap), its sampling noise is a fixed tiny per-corner offset, not per-lap jitter.

Net: with interpolation + 3-5 m sampling + EMA, the delta is accurate to well under 0.1 s in the regime that matters.

Windowed search (your point #2)

Ship the windowed search as the implementation — don't wait on more field data — but keep LOOK_BACK/LOOK_FORWARD as named constants so tuning later is a one-line change, and cover it with deterministic Layer-2 synthetic tests (driver gaining and losing time across both window bounds). That gives us real validation now; real-world window tuning can follow without code surgery.

Don't alias getLapDelta() -> pace on Mega

getPaceDifference() returns a pace ratio; getLapDelta() returns seconds. Returning a different-meaning number under the same name is exactly the dishonest-API trap we've been bitten by. Instead: on AVR getLapDelta() isn't compiled, expose a bool hasLapDelta() capability query, and let the example sketch do the fallback (hasLapDelta() ? getLapDelta() : getPaceDifference()) with distinct OLED labels. Fallback is display policy, app-side.

Still required to merge

Layer-2 tests (convergence to a known offset; EMA state preserved when rawDelta > ±120 s; windowed gain/loss across bounds; overflow refuses promotion), Doxygen on new public methods, ## [Unreleased] CHANGELOG entry, README mention. One logical change per PR, branch off master.

The validated core (EMA, ±120 s guard, throttle, windowed search) is all kept — the changes are: distance-sampled static double buffer, compile-gated off AVR, interpolate between samples, drop speed, honest capability fallback.

---

Generated by Claude Code