FEATURE: Embedded general-purpose stopwatch timer

[FabioRoss]

What problem are you trying to solve?

DovesLapTimer measures lap and sector times precisely. But there are intervals
the user wants to time that aren't laps or sectors:

• How long has the driver been in the pit lane? (independent of service sector
  crossing times — the user might want a "pit lane timer" that the mechanic
  can start/stop manually)
• How long since the session started?
• Countdown display: "X seconds until mandatory pit window opens"
• Time a refuelling stop with a button press

All of these need a start/stop/read timer. Users implement this themselves with
unsigned long timerStart = millis() and arithmetic, but it's error-prone and
duplicated across projects. A clean embedded timer with state machine semantics
makes this trivial.

DovesLapTimer already manages multiple time references internally. Adding a
user-accessible one-slot general-purpose timer costs almost nothing.

Proposed solution

Embed a minimal stopwatch timer with a 3-state machine:

struct TimerState {
  unsigned long startTimestamp;
  unsigned long stopTimestamp;
  uint8_t state;  // 0 = idle, 1 = running, 2 = stopped (result available)
};

// Public member — user can start/stop/reset directly
TimerState timer;

ACCESSOR METHOD:

unsigned long getTimerElapsed() const;
// Returns: millis() - startTimestamp  if state == 1 (running)
//          stopTimestamp - startTimestamp  if state == 2 (stopped)
//          0  if state == 0 (idle)

CONTROL METHODS:

void timerStart() { timer.startTimestamp = millis(); timer.state = 1; }
void timerStop()  { timer.stopTimestamp = millis(); timer.state = 2; }
void timerReset() { timer.state = 0; timer.startTimestamp = 0; timer.stopTimestamp = 0; }
bool timerIsRunning() const { return timer.state == 1; }

(Alternatively, expose the TimerState struct as a public member and let the
user manage it directly — simpler API surface if control methods feel heavy.)

Alternatives considered

1. User manages their own unsigned long timerStart = millis() — current approach.
   Works but: no state machine, no "already stopped" semantics, no convenient
   result-available state.

2. Use lastServiceSectorTime (Issue FEATURE: Service sector detection (pit lane, refuelling, tyre stops) #30) — tracks service stop duration, but
   only fires on defined crossing lines. Can't be triggered by a button press.

3. Arduino's built-in millis() — the underlying mechanism, but no wrapper.
   The value of the embedded timer is the state machine semantics, not the math

[TheAngryRaven]

Approved for the library — with one mandatory change to the clock source and careful rollover handling.

1. Use the library's injected GPS time, not millis(). The core never calls millis() — all timing runs on the GPS time fed via updateCurrentTime() (millisecondsSinceMidnight). That's deliberate: it's what keeps the suite replay-testable and the core free of a hardware-clock dependency. The stopwatch must use the same source:

• timerStart() captures millisecondsSinceMidnight (not millis())
• timerStop() captures millisecondsSinceMidnight
• running-state elapsed = now - startTimestamp using the current millisecondsSinceMidnight

Bonus: GPS time is a better clock than millis() anyway — atomic-disciplined, no drift.

2. Midnight rollover — read this carefully, the obvious implementation is wrong. millisecondsSinceMidnight resets to 0 every 24 h, i.e. it wraps at 86,400,000, which is NOT a power of two. The usual Arduino millis() overflow trick — relying on unsigned subtraction now - start to self-correct across a wrap — works only because millis() wraps at 2^32. It does not work here: if a timer starts at 23:58 (start ≈ 86,280,000) and you read it at 00:01 (now ≈ 60,000), then now - start underflows to ~4.29 billion — garbage. You must do explicit modular arithmetic against the day length:

static const unsigned long MS_PER_DAY = 86400000UL;

// works for a single midnight crossing
unsigned long elapsed = (now >= start)
    ? (now - start)
    : (MS_PER_DAY - start + now);

Apply the identical logic to the stopped state (stopTimestamp vs startTimestamp). Constraints to document right next to the method:

• Correct for one midnight crossing only. An interval > 24 h is ambiguous (can't tell 0.5 h from 24.5 h) — document that measured intervals must be < 24 h. Fine for pit/session/refuel timing; not a wall-clock substitute.
• This is why elapsed must go through getTimerElapsed() and the struct should NOT be a raw public member — centralize the wrap math in one place so users can't compute stop - start themselves and get it wrong. Pick the control-methods API (timerStart/timerStop/timerReset/timerIsRunning/getTimerElapsed) over exposing TimerState.

3. Document the GPS-rate behavior: elapsed only advances when updateCurrentTime() is called, so resolution is the GPS update rate (~40 ms at 25 Hz), and the timer freezes if GPS drops out. Totally fine for second-scale pit/session timing — just don't let anyone expect millisecond precision or a free-running clock. Also note: feed GPS time before starting the timer, or startTimestamp will be stale/zero.

4. State machine as proposed is good — keep idle/running/stopped, getTimerElapsed() returns 0 when idle, current-time delta when running, stop - start when stopped.

Required to merge: Layer-2 tests including a rollover case (start near end of day, read/stop after midnight → correct elapsed), plus idle/running/stopped transitions; Doxygen on the public methods; ## [Unreleased] CHANGELOG entry; README mention. One logical change per PR, branch off master.

(Noting for the record: a general-purpose stopwatch is logger-side by nature — it's landing in the timing core only because it rides the GPS clock for free and stays tiny. When the logging library eventually splits out, this is a clean candidate to move.)

---

Generated by Claude Code