FEATURE: Per-sector delta timing (vs best and optimal) with live lap progress delta

[FabioRoss]

What problem are you trying to solve?

The current sector timing API (getBestSector1/2/3Time, getCurrentLapSector1/2/3Time)
tells you what the times WERE. What it doesn't tell you is:

1. "Was that sector better or worse than my best?" (signed delta, seconds)
2. "Was that sector better or worse than my optimal?" (independently best sectors)
3. "Based on my sector splits so far this lap, am I ahead or behind my best lap?"

These three questions are what racing engineers look at lap-by-lap. Without them,
the user has to compute (currentLapSector1Time - bestSector1Time) / 1000 in their
sketch and track it separately. This math belongs in the library.

Note: this is complementary to Issue #29 (GPS delta) — sector deltas update at
each line crossing, GPS delta updates every fix. Both are useful simultaneously:
sector delta = authoritative split result; GPS delta = live in-corner feedback.

Proposed solution

Extend sector timing with per-sector delta fields and a lap-level running delta.

NEW SECTOR FIELDS (extend current sector timing storage):

// For each completed sector, after crossing:
float deltaBest;      // (sectorTime - bestSectorTime) / 1000.0f — signed seconds
float deltaOptimal;   // (sectorTime - optimalSectorTime) / 1000.0f — signed seconds
unsigned long optimal; // rolling best individual sector time across ALL laps
                       // (updates independently of whether the lap is a best lap)

The distinction between "best" and "optimal" matters:

• bestSectorN = sector N time from the best COMPLETE LAP
• optimal = best sector N time ever, regardless of what the rest of that lap was
  These can differ significantly in karting where one great sector often coincides
  with a poor sector elsewhere.

NEW LAP-LEVEL ACCUMULATOR:

float microsectorLapDelta;   // running sum: Σ deltaBest for sectors completed
                             // this lap; gives "where am I vs best lap?"
                             // before the lap ends
float previousLapDelta;      // microsectorLapDelta preserved at lap completion
                             // for display (so it doesn't reset to 0 on crossing)

DELTA CALCULATION (at each sector crossing):

long deltaMs = (long)currentSectorTime - (long)bestSectorTime;
deltaBest = deltaMs / 1000.0f;

long deltaMsOpt = (long)currentSectorTime - (long)optimalSectorTime;
deltaOptimal = deltaMsOpt / 1000.0f;

// Rolling optimal: update regardless of lap result
if (optimalSectorTime == 0 || currentSectorTime < optimalSectorTime) {
  optimalSectorTime = currentSectorTime;
}

// Accumulate lap progress delta
microsectorLapDelta += deltaBest;
// On finish line crossing: preserve and reset
previousLapDelta = microsectorLapDelta;
microsectorLapDelta = 0.0f;

PROPOSED PUBLIC API:

float getSectorDeltaBest(int sectorNumber) const;     // signed seconds vs best
float getSectorDeltaOptimal(int sectorNumber) const;  // signed seconds vs optimal
unsigned long getOptimalSectorTime(int sectorNumber) const;  // rolling optimal ms
float getLapProgressDelta() const;   // microsectorLapDelta (running this lap)
float getPreviousLapDelta() const;   // delta at end of last lap

Alternatives considered

1. User computes (getBestSector1Time() - getCurrentLapSector1Time()) themselves —
   current workaround. Two calls, user math, no optimal tracking. Every karting
   display project reinvents this.

2. getOptimalLapTime() (already exists) — sums best sectors after the fact but
   doesn't give per-sector signed deltas or the live accumulated lap delta.

3. Include only deltaBest, not deltaOptimal — simpler, but misses the "theoretical
   best lap" concept that is standard in professional timing systems.

[TheAngryRaven]

Great feature — this is squarely derived math on sector data the library already tracks. One important correction before coding, because half of this already exists under a different name:

The library's existing bestSectorN is already your "optimal." updateBestSectors() (DovesLapTimer.cpp:644) updates each sector's best independently across all laps, regardless of whether the lap as a whole was a best lap — and getOptimalLapTime() sums them. So your proposed optimal field is a redundant copy of bestSectorN, and the proposed naming inverts the library's existing convention (here "best sector" already means best-ever, not "sector from the best lap"). Please don't add a second optimal store — reuse bestSectorN. Two different meanings of "best sector" in one class is exactly the kind of naming trap we've been bitten by before.

What's actually missing is the opposite half: the per-sector splits of the single best complete lap. The library keeps bestLapNumber but discards that lap's S1/S2/S3. Add a bestLapSectorN[3] store, captured atomically right where bestLapTime is set (DovesLapTimer.cpp:143-147). That's the genuinely new piece.

Suggested API mapping (keeps existing names intact):

• getSectorDeltaOptimal(n) = currentLapSectorN - bestSectorN (existing best-ever sector)
• getSectorDeltaBestLap(n) = currentLapSectorN - bestLapSectorN (new best-complete-lap split) — renamed from getSectorDeltaBest so "best" isn't overloaded
• getLapProgressDelta() / getPreviousLapDelta() — keep as proposed
• Drop getOptimalSectorTime(); it's the existing getBestSectorNTime().

On the indexed getters — yes, please use the getSectorDeltaOptimal(int sectorNumber) style you proposed rather than …Sector1/2/3 triplets. That's a deliberate, welcome convention for new sector APIs going forward (the existing triplet getters stay as-is for back-compat). Bounds-check sectorNumber and return 0 for out-of-range, consistent with the no-data convention below.

Free correctness invariant for the test suite: since microsectorLapDelta accumulates Sum of deltaBestLap, over a full lap it must equal (thisLapTime - bestLapTime)/1000 within rounding. That's a strong Layer-2 assertion — please include it alongside the per-sector delta tests and a "before any valid best lap, all deltas return 0" guard test.

Smaller notes:

• Guard every new getter with the existing "0 = no data yet" convention (return 0 before a valid best/best-lap exists, like getOptimalLapTime/getPaceDifference).
• bestLapSectorN must use the same S2<->S3 remap that reverse-direction already applies to bestSectorN, so deltas stay correct when direction is reversed.
• Memory is a non-issue (a few floats + 3 longs, no heap) — AVR-safe, keep it.

Required to merge: Doxygen on all new getters, ## [Unreleased] CHANGELOG entry, README mention, and the Layer-2 tests above. One logical change per PR, branch off master.

---

Generated by Claude Code