[ON HOLD] FEATURE: GPS proximity circuit auto-detection (instant, no lap required)

[FabioRoss]

What problem are you trying to solve?

Setting up sector lines before every session is error-prone and inconvenient.
Users shouldn't have to hardcode GPS coordinates in their sketch if they race
at known circuits. And on competition day, the timer needs to be ready
immediately — not after driving a detection lap.

The upstream CourseDetector already solves multi-layout detection via driven
distance (drive ~1 lap, compare odometer to each course's expected length).
This is excellent for venues with multiple layouts where distance is the
discriminator.

But there's a simpler, faster alternative for single-layout venues or any
situation where GPS coordinate proximity is sufficient:
"I'm within X meters of circuit center point A → load circuit A's sector lines."

This works on the FIRST GPS fix after power-on — no driving required.

Proposed solution

Add a GPS proximity scan that finds the nearest pre-configured circuit and
auto-loads its sector definitions.

KEY METHOD:

const CircuitStruct* findClosestCircuit(double currentLat, double currentLon);

• Scans a PROGMEM database of CircuitStruct entries
• For each: haversine(currentLat, currentLon, circuit.lat, circuit.lon)
• Returns pointer to nearest circuit entry (always returns SOMETHING)
• Caller decides whether the returned circuit is "close enough" via their
  own distance threshold (or just trust it if only one circuit is in the DB)

CIRCUIT LOADING:

void loadCircuit(const CircuitStruct* ptr);

• deep-copies circuit data from PROGMEM into RAM
• dynamically allocates sector and service sector arrays (malloc)
• sets circuitLoaded = true
• gates loop() processing until circuitLoaded

CIRCUIT DATA STRUCTURE (PROGMEM-stored):

struct CircuitStruct {
  const char* name;
  double lat, lon;           // circuit center point for proximity detection
  uint8_t numSectors;
  const SectorStruct* sectors;          // sector line GPS coordinates
  uint8_t numServiceSectors;
  const serviceSectorStruct* serviceSectors;
};

ADDITIONAL METHODS:

void reloadCircuit();     // clears circuitLoaded, triggers re-detection
bool circuitLoaded;       // public readable — safe to check before loop()

COMPARED TO CourseDetector:

CourseDetector (upstream):
- Detects via DRIVEN DISTANCE (compare odometer to course.lengthFt ±25%)
- Requires completing ~1 lap before detection resolves
- Better for multi-layout tracks at same venue (same GPS location, different distance)
- Handles up to MAX_COURSES simultaneously

GPS Proximity (this proposal):
- Detects via GPS COORDINATE DISTANCE (haversine to circuit center)
- Works on FIRST GPS FIX — instant
- Better for known single-layout circuits where GPS proximity is unambiguous
- Simpler implementation, less RAM overhead

These are COMPLEMENTARY approaches. A possible architecture: try GPS proximity
first (instant, good enough for 90% of cases); fall back to CourseDetector if
multiple circuits are within the proximity threshold.

CIRCUIT DATABASE DESIGN:

The database should live in user-provided PROGMEM in the sketch or a separate
.h file (not hardcoded inside the library itself). The library provides:
- The CircuitStruct/SectorStruct data types
- findClosestCircuit() and loadCircuit() methods
- The user provides their own array of CircuitStructs

This keeps the library hardware-agnostic and geography-agnostic — the library
doesn't need to know about any specific track.

Alternatives considered

1. CourseDetector (upstream's current approach) — driven-distance based.
   Works great for multi-layout tracks but requires completing a detection lap.
   Complement, not replacement.

2. User calls setStartFinishLine() / setSector2Line() / setSector3Line() manually —
   current baseline. Works but requires hardcoding coordinates in the sketch.
   Error-prone if the user races at multiple circuits.

3. Automatic on every GPS fix inside loop() — what RaceBoard does. Less suitable
   for the library itself; better as a user-implemented pattern using
   findClosestCircuit() as the building block.

[FabioRoss]

This was tested and working in real world tests. Would probably benefit of a way to load user tracks via SD (web tool creates .csv or .json, user copies onto SD card, library scans SD and loads), but this would mean having to implement SD support built into the library

[TheAngryRaven]

Yea that seems like a datalogger feature, so I've already barked down that tree, it's actually painful to reread all that data post-session.

The honest solution to that is what I've recently done, customer file!
.dovex is dead simple

There's like 2kb of dead header data (like 2048 empty rows)
Followed by a header row, and then every proceeding row is the raw data.

After the sessions has ended (in my project, no movement for 10 seconds), then it dumps the metadata at the top of the file.

So the replay function just quickly loads the laptimes!!

You could easily make your own version of this, just rip the code straight out of the datalogger.

20260404_1614.dovex.txt

[TheAngryRaven]

Though.... That now makes me ponder if we need a second library.... The timing Library and the logging library haha

[TheAngryRaven]

To the course detection part, that's already a core feature of the library now, I added it last month!

https://github.com/TheAngryRaven/DovesLapTimer#option-2-coursemanager-multi-course-automatic-detection

It has the ability to do automatic course detection, and a "lap anything mode", when a certain speed is reached, it will drop a waypoint, this waypoint is then used for laping anything anywhere.

[TheAngryRaven]

Circling back on this with @FabioRoss — after digging in, the short version is we (on the maintainer side) were conflating two different things, and untangling them is what settles this issue:

• Course detection (what the library does today via CourseManager/CourseDetector): disambiguates layouts at the same venue by driven distance. Necessary because we run up to 6 layouts stacked on the same patch of asphalt — they share a center point, so coordinate proximity can't tell them apart.
• Track detection (what you're proposing here): picks which venue you're at by coordinate proximity, instantly on the first fix. That's genuinely useful and genuinely missing — but it's a level above course detection, not a replacement for it.

So your "try proximity first, fall back to CourseDetector" instinct was right; it was just pinned at the wrong granularity (the proposal's CircuitStruct conflates venue and layout the same way we were conflating the terms).

Here's the thing though: track detection already exists in the datalogger, where it's deliberately wired to pick the venue before doing any SD reads (so we're not re-reading config every fix). That orchestration — "decide venue, then load that venue's config" — is config-loading lifecycle, which is exactly the kind of SD/storage concern we've kept out of the core library on purpose. Pulling it into the library would either drag SD/config loading across the architecture boundary, or balloon RAM (CourseManager peaks ~24 KB during detection; holding one per venue isn't viable).

That makes this another data point for splitting out a dedicated logging/session library alongside the timing library — track selection, SD, .dovex, and session persistence all cluster on that side of the line.

So we're going to put this one on hold rather than close it — the feature's legit, but it lands cleaner in a future logger library than bolted onto the timing core. Appreciate the writeup; the comparison table in the issue is what made the distinction click.

---

Generated by Claude Code