[NEEDS MORE DISCUSSION] FEATURE: Session-persistent lap state injection (setLapsData)

[FabioRoss]

What problem are you trying to solve?

DovesLapTimer's reset() starts completely fresh. This is fine for a single
session, but real devices face two common scenarios where historical data needs
to survive:

SCENARIO A — Device restart mid-session:
The microcontroller reboots (power blip, watchdog reset, ...)
mid-session. If the user has saved laps/bestLapTime to SD or EEPROM, they
want to reload those values into the timer so the display shows the session's
running best, not "0". Without a way to inject this state, the user must
maintain their own parallel shadow copy of all timing state and avoid calling
the library's getters entirely.

SCENARIO B — "Best ever" mode:
At the start of a race day, the user loads their all-time best lap from
persistent storage so the delta display compares against the absolute best,
not just the current session's best. Currently impossible without hacking the
private bestLapTime member.

There is no API to set bestLapTime, laps, or lastLapTime from outside the
library. These are private state with no setter except through crossing events.

Proposed solution

Add a setLapsData() method that allows pre-loading core session state:

void setLapsData(
  int readLaps,
  unsigned long readLastLapTime,
  unsigned long readBestLapTime
);

Implementation (3 lines):
this->laps = readLaps;
this->lastLapTime = readLastLapTime;
this->bestLapTime = readBestLapTime;

This is intentionally minimal — it sets the three fields most likely to be
restored from external storage. It does NOT set sector times, odometer, or
timestamps (those are session-specific and would be meaningless to restore).

OPTIONAL EXTENSION (could be a separate PR):

void setBestSectorTimes(
  unsigned long s1, unsigned long s2, unsigned long s3
);

Allows restoring best sector times alongside lap times for the sector delta
display (Issue #31) to work correctly from session start.

SESSION NUMBER TRACKING (companion concept):

A session counter that increments each time the device starts and a circuit
is loaded — useful for SD log file naming and display. Example:

int currentSessionNumber = 1;  // readable by user code

The session number is incremented externally (by SD logger, EEPROM, etc.) and
injected via a simple setter. The library just stores and exposes it:

void setSessionNumber(int n) { currentSessionNumber = n; }
int getSessionNumber() const { return currentSessionNumber; }

Alternatives considered

1. User maintains a separate "best lap" variable outside the library —
   current workaround. Means the user can never rely on getBestLapTime() for
   the true best; they need their own shadow variable. Defeats the purpose of
   a library.

2. Make bestLapTime public — breaks encapsulation; no setter semantics.

3. Serialize/deserialize the entire timer state — complex, version-dependent,
   not all state is meaningful to restore (odometer, position, buffer state).
   setLapsData() is the minimal useful interface.

[TheAngryRaven]

Love this one, but it has too many entangled considerations to spec right now and it depends on other issues landing first — so putting it on hold to circle back. Capturing the full design surface here so we pick it up with everything in view.

Why hold

• Depends on FEATURE: GPS-based real-time lap delta (gap to reference lap) #29 (delta reference vector) and FEATURE: Per-sector delta timing (vs best and optimal) with live lap progress delta #31 (best-ever vs best-lap sector storage) being implemented first — those define what state even exists to persist.
• It's the most logger-flavored issue in the batch (persistence = SD/EEPROM I/O), so it's also a prime candidate for the eventual logger library split rather than the timing core.

The headline realization (the reason to do this at all)

Restoring laps/lastLapTime/bestLapTime is the trivial part. The real prize: persist #29's distance-sampled reference lap vector, reload it at boot, and getLapDelta() works against your saved best from lap one — "best-ever pace delta" that survives reboots and carries across race days. #29 is already being designed with the hooks for exactly this (getReferenceLap(count) / setReferenceLap(ptr, count)). So this issue is really "persist + re-inject the #29 reference," not "set three longs."

State-consistency landmines (inject in consistent groups, never loose fields)

• bestLapTime without bestLapDistance silently breaks getPaceDifference() — it divides by bestLapDistance (DovesLapTimer.cpp:830). So restore those two together.
• Same for FEATURE: Per-sector delta timing (vs best and optimal) with live lap progress delta #31: don't restore a bestLapTime inconsistent with restored sector sums; keep best-ever-sector vs best-lap-split (the FEATURE: Per-sector delta timing (vs best and optimal) with live lap progress delta #31 distinction) mutually consistent.
• The issue's instinct to skip odometer/timestamps is right — but we need to audit every getter that reads restored state and confirm it stays consistent, not just trust it.

Memory / storage tiers

• Tier 1 — scalar restore (laps, bestLapTime+bestLapDistance, best sectors): a few bytes, EEPROM-friendly, works on any target.
• Tier 2 — full delta reference (FEATURE: GPS-based real-time lap delta (gap to reference lap) #29 vector): ~400 points x ~12-16 B ≈ 5-7 KB at 3-5 m sampling. Won't fit AVR EEPROM — this is an SD-only feature, and it's non-AVR anyway since FEATURE: GPS-based real-time lap delta (gap to reference lap) #29 itself is gated off Mega. Design the API so Tier 1 and Tier 2 are independently usable.
• Versioning is mandatory for Tier 2: a serialized reference encodes sample distance + point layout. A stale file from a different firmware version must be rejected (magic + version header), not loaded blindly into a garbage delta. Ties into the .dovex format discussion.

Load mechanism — manual vs automatic

• Library stays I/O-free (architecture boundary): it only provides injectors (setLapsData, setBestSectorTimes, setReferenceLap). It never touches SD/EEPROM itself.
• Manual (preferred for the core): app reads storage at boot and calls the setters before the first loop(). Explicit, clean boundary. Document "inject before first loop / on idle state only."
• Automatic: belongs in the logger lib / example, not the core — and it must be keyed to the detected track/course (interacts with parked [ON HOLD] FEATURE: GPS proximity circuit auto-detection (instant, no lap required) #35). Loading Track A's best lap while sitting at Track B produces nonsense delta, so auto-load has to validate against the loaded circuit before injecting.

Scope cuts

• sessionNumber: cut from the library. It's pure SD-file-naming concern with zero library value (unlike speed, which the library actually computes). Keep it app-side / logger-lib.

Open questions for circle-back

• reset() interaction: is injection allowed only from a fresh/idle state, or any time? Define and document.
• Do we expose Tier 1 and Tier 2 as separate methods, or one grouped "restore session" call? Leaning separate, so a no-SD EEPROM user can do Tier 1 alone.

Parking here until #29 and #31 land — then this becomes "serialize/restore the reference + a consistent scalar group," likely in the logger library.

---

Generated by Claude Code