FEATURE: Service sector detection (pit lane, refuelling, tyre stops)

[FabioRoss]

What problem are you trying to solve?

Circuit racing — especially endurance karting — involves mandatory service stops:
pit lane entry/exit, refuelling windows, tyre changes. A lap timer that can only
detect the start/finish line and race sectors has no way to:

• Notify the driver/display when they enter or exit the pit lane
• Time how long a service stop took
• Log which type of service was performed

Currently users must maintain separate crossing-line detection logic using the
same underlying haversine/side-of-line math that DovesLapTimer already implements.
This is boilerplate duplication.

The library's crossing detection infrastructure (insideLineThreshold,
pointOnSideOfLine, side-change confirmation) is exactly the right foundation
for service sector detection — it just needs to be exposed for non-race lines.

Proposed solution

Add "service sector" as a first-class line type alongside race sectors.

DATA TYPES:

struct serviceSectorStruct {
  double lat1, lon1;       // line endpoint A
  double lat2, lon2;       // line endpoint B
  bool isEntrance;         // true = entry line, false = exit line
  uint8_t serviceType;     // one of the SERVICE_TYPE_* constants
};

// Type discriminators for sector_crossed_callback context
#define SECTOR_TYPE_RACE     0
#define SECTOR_TYPE_SERVICE  1
#define SECTOR_TYPE_OTHER    2

// Service types
#define SERVICE_TYPE_PITLANE_START   0
#define SERVICE_TYPE_PITLANE_END     1
#define SERVICE_TYPE_FUEL_START      2
#define SERVICE_TYPE_FUEL_END        3
#define SERVICE_TYPE_TYRES_START     4
#define SERVICE_TYPE_TYRES_END       5
#define SERVICE_TYPE_OTHER_START     6
#define SERVICE_TYPE_OTHER_END       7

API:

// Register callback: fires when any service sector line is confirmed crossed
typedef void (*ServiceCallbackFunction)(uint8_t serviceType, bool isEntry);
void setServiceSectorCallback(ServiceCallbackFunction cb);

// Public state readable by display code
bool inServiceSector = false;
unsigned long lastServiceSectorTime = 0;  // ms duration of last completed stop

// Config: max 8 service sectors (avoids heap pressure from unbounded array)
serviceSectorStruct* serviceSector = nullptr;
int numberOfServiceSectors = 0;

DETECTION LOGIC:

For each registered service sector line, per GPS fix:
1. insideLineThreshold() — quick reject if far from line
2. pointOnSideOfLine() — determine which side driver is on
3. Per-sector side history serviceSideLastSeen[8] — confirmed crossing
only when side changes from a non-zero previous side
4. Update inServiceSector and serviceSectorStartTime on entry
5. Compute lastServiceSectorTime = now - serviceSectorStartTime on exit
6. Fire callback(serviceType, isEntrance)

Service sector detection is independent of race sector crossing state —
both can be checked in the same loop() call without interference.

ARCHITECTURE NOTE:
For consistency with the shared _detectLineCrossing() zone state machine
added in v4.1, service sectors should ideally go through the same pipeline.
The main consideration is buffer sharing — service sectors are unlikely to
coincide with race sector crossings, but the architecture should be explicit
about this (separate flags, or confirmed non-overlapping zones in the track
config).

Alternatives considered

1. User implements their own crossing logic — current workaround. Requires
   duplicating insideLineThreshold, pointOnSideOfLine, and side-history logic.

2. Treat service sectors as race sectors — mixes race and non-race timing in
   the same sectorTimes[] array, polluting race stats with pit durations.

3. Separate library — over-engineered for what is ultimately reusing the same
   crossing detection math that already lives in DovesLapTimer.

[TheAngryRaven]

Strong feature and the right instinct to reuse the existing crossing math rather than fork a separate library. A few design notes before coding — one of them changes the approach materially:

1. Do NOT route service sectors through _detectLineCrossing() / the shared buffer. Your DETECTION LOGIC section (side-history + insideLineThreshold gate) is correct; the "ARCHITECTURE NOTE" suggestion to reuse the _detectLineCrossing pipeline contradicts it and would break things. The race pipeline uses a single shared crossingPointBuffer with mutual exclusion — only one line can be mid-crossing per loop() (see DovesLapTimer.cpp:55-104). Pit entry often sits right next to start/finish, so a shared buffer means a pit-in can get silently dropped while S/F is crossing (and 8 service lines contending for one buffer compounds it). Keep service detection as its own lightweight parallel codepath: reuse insideLineThreshold() + pointOnSideOfLine() for the math, but with independent per-line side state and no shared buffer. That's also what makes your "independent of race state, same loop() without interference" claim actually true. Service stops are seconds-to-minutes, so they don't need the interpolation race timing relies on — a confirmed side change is plenty.

2. Add jitter hardening. A single noisy GPS fix flipping sides shouldn't fire a crossing. Require the insideLineThreshold zone gate AND a confirmed side change (a small debounce / two-fix confirmation). Otherwise pit-adjacent noise will spam the callback.

3. Collapse the service types — they're over-specified. {PITLANE,FUEL,TYRES,OTHER}x{START,END} double-encodes entry/exit, which is already carried by the struct's isEntrance and the callback's isEntry. Drop the START/END half. Better: make serviceType an opaque uint8_t tag the user assigns meaning to, rather than the core library hardcoding "FUEL"/"TYRES" (that's application semantics; the library deals in geometry + timing). Ship the named values as optional suggested constants users can ignore or extend. This makes it a generic auxiliary-line detector with unlimited categories.

4. Callback convention (this is the library's first callback, so let's set it right). Bare C function pointer is the correct embedded choice — please don't reach for std::function (heap/overhead on AVR). Add one thing now: an optional void* userData context pointer stored alongside each callback and passed back to it, so C++ users can route into an instance method (a plain function pointer can't capture this). Every callback in the library should follow this same shape.

5. Yes — include the unified sector-crossed callback in this PR. Keep the SECTOR_TYPE_RACE/SERVICE/OTHER discriminator; it now has a real consumer. Wire a setSectorCrossedCallback(...) that fires on every confirmed race line crossing (start/finish + S2 + S3) with the sector type + index + crossing time, alongside the service callback. Both follow the same void* userData convention from note 4. This is the piece that lets a datalogger drop its hand-rolled crossing-line handling, so it's worth doing together. Suggested split: land the service-sector detection and the sector-crossed callback as the two halves of this PR, keep everything else out.

6. Memory looks good as proposed: user-owned serviceSectorStruct* array + numberOfServiceSectors (matches the existing CourseConfig pattern — no heap allocation by the library; users can place it in flash/PROGMEM), fixed serviceSideLastSeen[8], cap at 8. Keep it.

7. Scope/limitation to document: a single inServiceSector flag + one serviceSectorStartTime means no nested/overlapping service zones — any entry starts the timer, any exit stops it. That's fine for v1; just call it out as a known limitation in the docs.

Required to merge (CLAUDE.md / CONTRIBUTING):

• Layer-2 unit tests: drive a synthetic line both directions -> service callback fires with correct (serviceType, isEntry); a single side-flip without a real crossing does NOT fire; lastServiceSectorTime computed correctly on entry->exit.
• Layer-2 unit test for the sector-crossed callback: fires once per confirmed race crossing with the right SECTOR_TYPE_* + index, and does not double-fire within a single zone.
• Regression guard: race lap times unchanged with service sectors + callbacks active (proves no buffer contention or extra firing crept in) — ideally confirm against the Layer-3 NMEA replay fixtures.
• Doxygen on all new public methods, ## [Unreleased] CHANGELOG entry, README mention.
• One logical change per PR — service sectors + the two callbacks only, branch off master.

---

Generated by Claude Code

[TheAngryRaven]

I like the idea of various service types, but for now that requies some more thinking, single service lane for now.

I have I think a better idea (for later not now), geofences, single "service area" with internal geofences for fuel/driver/etc

[FabioRoss]

few clarifications:

1- you're right, sorry about the conflicting strategies
2- alright, i'll mimic the current state of the library
3- fair point
4- the userData pointer is a great idea, alright for the bare c function pointer, probably cleaner anyways
5- as you prefer, maybe open a separate issue regarding it but include the sectorCrossedCallback to this PR?

---

I have I think a better idea (for later not now), geofences, single "service area" with internal geofences for fuel/driver/etc

in some tracks there are completely separate areas for refueling and driver change (i mean completely different pitlanes, not only different areas in the same pitlane). Geofencing is a nice idea though. I also don't think the single service area needs to have adiecent geofences, so probably this is a non-issue (either you're in service or not, regardless of which service)

[TheAngryRaven]

Yea include the call back here why not, it will set the stage for using them in the future

[TheAngryRaven]

Correction to my earlier comment here, to keep the PRs from colliding: the sector-crossed (race) callback belongs in #32, not bundled into this one. Reasoning — the race callback is standalone callback infrastructure with no dependency on service sectors, whereas this issue's service detection depends on that convention. So #32 lands first, and this PR builds on it.

Two specific walk-backs from my earlier comment:

• Disregard "include the unified sector-crossed callback in this PR" — that work moves to FEATURE: Sector-crossed event callback with rich crossing context #32.
• Disregard "keep the SECTOR_TYPE_RACE/SERVICE/OTHER discriminator." We're going with two separate callbacks (race in FEATURE: Sector-crossed event callback with rich crossing context #32, service here), which makes the discriminator vestigial — drop the enum.

Everything else in my earlier comment on this issue still stands (lightweight side-change detection separate from the shared crossingPointBuffer, jitter hardening, opaque serviceType tag, void* userData convention, memory layout, the v1 no-nested-zones limitation, and the test/doc requirements). The service callback here just reuses the userData callback convention established in #32:

typedef void (*ServiceSectorCallback)(uint8_t serviceType, bool isEntry, void* userData);
void setServiceSectorCallback(ServiceSectorCallback cb, void* userData = nullptr);

---

Generated by Claude Code