[2.8.0] - Waypoint Geofences

[jamesarich]

Client tracking issue for Waypoint geofences — parent spec: meshtastic/design#114.

Proto pinned via #6003 (2.7.26-06d729a-SNAPSHOT); UI/logic unwired. Wire the new Waypoint geofence fields (geofence_radius, bounding_box, notify_on_enter, notify_on_exit, notify_favorites_only):

• Room: add geofence columns + migration
• Copy proto geofence fields on waypoint receive
• Geofence section in the waypoint editor (radius — locale-aware units, not Apple's imperial table; drag-to-define bounding box; enter/exit + favorites-only toggles)
• Map overlays: circle + rectangle per waypoint
• Alert engine: point-in-circle (haversine) / point-in-box on each received position; in-memory (waypointId, nodeNum) crossing state, baseline-on-first-sighting; notification gated by enter/exit + notify_favorites_only; deep-link to waypoint. No OS Geofencing API (crossing is judged on other nodes' positions, not own location).

Behavior spec + reference implementation (Apple): design#114.

[jamesarich]

Draft PR up: #6014. Status against the scope checklist, with a couple of findings worth recording.

Scope item	Status
Room: add geofence columns + migration	N/A on Android — see finding 1
Copy proto geofence fields on waypoint receive	✅ (free via the serialized-proto round-trip)
Geofence section in the waypoint editor	✅ (locale-aware radius, drag-to-define box, gated toggles)
Map overlays: circle + rectangle per waypoint	✅ on both flavors (Google Maps + OSMDroid)
Alert engine (point-in-region, crossing state, notify)	⚠️ implemented + tested but frozen — see finding 3

Findings during implementation

1. No Room columns/migration needed on Android. Unlike Apple's SwiftData model, we store waypoints as serialized
   proto bytes inside the existing Packet.data (DataPacket), so the new geofence fields round-trip for free on
   both receive and send. Adding denormalized columns would buy nothing (nothing queries waypoints by geofence). I
   skipped the migration — the proto fields are verified present in the pinned 2.7.26-06d729a jar.

2. getWaypoints() is a row-per-transmission firehose. It returns one row per transmission (re-broadcasts/edits
   insert new rows) and never filters expiry. Both the map and the engine now share one activeWaypointPackets()
   normalizer (latest-wins by waypoint id + expiry drop) so stale/expired geofences can't fire — otherwise expired
   waypoints keep alerting. Caught in review, covered by a test.

3. Open question — who computes the crossing? Per the current discussion, the firmware may compute crossings
   and push a notification to the phone, rather than every client evaluating positions (which is what spec
   [PARENT] [ALIGNMENT]: Waypoint Geofences design#114 currently says). The client alert engine in this PR is therefore frozen: built and
   tested, but not extended/wired further pending that decision. If the firmware model is adopted, it would be
   replaced by a handler for a firmware→phone notification packet (likely needs an upstream proto + firmware change
   first). Raised on the spec thread.

Deferred (tracked as PR follow-ups)

Engine items to revisit after the firmware decision (collector .catch resilience, ±90/±180 position bounds,
concurrent-position ordering, expiry re-check cadence, positive notify-path tests) plus a few non-engine items
(hoist duplicated displayUnits; map-overlay non-visual a11y cue; keyboard/screen-reader box authoring). Full list in
the PR description.

[jamesarich]

Closing — waypoint geofences are wired on Android via #6014 (merged 2026-07-01): geofence editor (locale-aware radius, drag-to-define bounding box, enter/exit + favorites-only toggles), circle + rectangle map overlays on both flavors (Google Maps + OSMDroid), proto geofence fields round-tripping on waypoint receive/send, and a working client-side enter/exit alert engine.

Verified end-to-end against the F-Droid/OSMDroid build via the MCP replay harness:

• Injected waypoint (geofence_radius=500, notify_on_enter/exit) renders its pin on the map and fires the 'Received waypoint' notification.
• Driving a tracker node's position outside → inside → outside the fence raises the crossing alerts as expected: entered <waypoint> then left <waypoint>. (The engine baselines on first sighting, so a real boundary crossing is required to fire — a single in-fence position only sets the baseline.)

Related work:

• Android: feat: Waypoint geofences (editor, map overlays, alert engine)  #6014 (merged)
• Apple: feat: geofence support on waypoints (circle + bounding box) Meshtastic-Apple#2001
• Web: feat(web): waypoint create/edit + geofences (design#114) web#1231
• Parent spec: [PARENT] [ALIGNMENT]: Waypoint Geofences design#114