Skip to content

Chapter 6 — Map & GPS

The Map tab gives spatial awareness of the team on two switchable layers: a geographic Map and a network-topology Mesh view.

6.1 The geographic map

The Map layer plots your own position and every teammate who is sharing GPS.

  • Your position appears as a glowing dot; the map auto-centers on your first GPS fix. A re-center button returns to your position at any time.
  • Teammates appear as name callouts anchored to their reported position. The status dot on each callout encodes position freshness:
Color Freshness
Green Fresh — reported within the last 60 seconds
Amber Recent — 1 to 5 minutes old
Grey Stale — more than 5 minutes old
  • Connection lines are drawn from you to each reachable teammate with a known position — solid for direct/WiFi links, dashed when the path runs over LoRa or the peer is offline; thicker lines indicate direct (0–1 hop) links.
  • A status chip summarizes the picture: "N in range · X direct · Y relay".
  • Helper banners appear when there's nothing to show: "No GPS fix — showing peer positions only" or "No peer positions yet — peers appear once they share GPS".

Map tiles come from OpenStreetMap and require internet access to load; positions, markers, and mesh data render regardless.

Position details

Tapping any marker opens a detail sheet with coordinates (6-decimal precision), altitude, speed, heading, accuracy (± meters), the position source (LOCAL GPS / VIA MESH / RELAYED), fix age, plus mesh details for peers: mesh ID, last seen, interface, hop count, and raw RSSI/SNR signal readings where available.

6.2 The Mesh view

Switch the header toggle to Mesh for a radial topology view — you at the center, every discovered peer arranged around you:

  • Solid green line — direct link.
  • Dashed amber line (with a relay glyph) — reachable through a relay.
  • Dashed grey line — finding a route.
  • Nodes acting as relay/transport nodes are marked with a ring and a RELAY badge.

The view refreshes every 10 seconds. Tapping a pin opens the same connection detail sheet used in chat. A first-visit explainer summarizes the legend and can be dismissed permanently.

6.3 How position sharing works

Position sharing is engineered to be useful on LoRa-class links without flooding them:

  1. The app reads the device GPS with high accuracy and forwards a fix to the engine only when the device has moved ≥ 10 m or 60 s have elapsed.
  2. The engine broadcasts positions to peers on a 60-second cycle, and only if the fix is fresh (under 5 minutes old) — a stale fix is never broadcast.
  3. Positions ride inside encrypted messages (as telemetry attached to announces and messages), so location data gets the same end-to-end encryption as message content.
  4. Received positions age out visually (freshness colors) rather than silently persisting as if current.

Position sharing follows the app's discovery/GPS settings — see Chapter 12 — Settings Reference.

6.4 Background mesh (mobile)

By default, mobile platforms suspend apps in the background, which pauses mesh participation when the phone is locked. The Background mesh toggle (Settings) opts the device into staying live:

  • Uses the OS location service to keep the app — and its embedded mesh engine — running while backgrounded or locked.
  • Requires the Always location permission with Precise Location enabled. The app walks the operator through the permission upgrade and never shows the toggle as on without a verified grant. If the OS permission is later downgraded, the toggle drops to off and the operator is notified.
  • While backgrounded, location accuracy is automatically reduced to the ~100 m tier to save battery (observed overnight cost ≈ 5%/8 h). The battery lever is accuracy, not update frequency — messages still deliver promptly.
  • With Background mesh off, a locked phone receives nothing until reopened; on unlock, the app re-attaches within a few seconds and held messages deliver.

Operational note: in v1 there are no push notifications. The Delivered proof on the sender's side is the authoritative signal that a locked peer's device received a message. For teams that need always-on receipt, enable Background mesh on receivers, or deploy a relay node at the site so messages are held on the mesh until phones wake.