Location Authority

The Eixam Connect SDK centralizes location selection so SOS, PRE-SOS/DMP, telemetry publishing, Android foreground/Protection Mode, and UI preview all use the same source-priority rules.

The goal is to avoid treating stale, cached, display-only, or relay-observed coordinates as if they were newly resolved backend-authoritative location.

Source Priority

When the SDK needs a location, SdkResolvedLocationResolver evaluates available sources and returns a SdkResolvedLocation with a SdkLocationSource.

Priority	Source	Authoritative use
1	remoteRelayDevice	Authoritative only for the specific remote/relay LoRa event that carried the payload. It must not become the local user's general current position.
2	connectedDevice	Preferred when the connected BLE device has a fresh, valid GPS fix. This wins over phone GPS.
3	phone	Fallback when no fresh, valid connected-device GPS is available.
4	cachedFallback	Display continuity only. It is not backend-authoritative for new SOS or telemetry publishing.
5	backendSnapshot	Display-only for existing incident views. It is not used to create new SOS or telemetry.

Public Model

SdkResolvedLocation represents the chosen SDK location sample. Host apps should use its source and freshness metadata to explain what is being displayed and whether the value can be used by SDK publishing flows.

SdkLocationSource identifies where the resolved sample came from:

• remoteRelayDevice
• connectedDevice
• phone
• cachedFallback
• backendSnapshot

SdkResolvedLocationResolver is the SDK resolver that applies the priority rules above. Backend SOS creation, PRE-SOS/DMP location use, telemetry publishing, foreground/Protection handoff, and UI preview should rely on resolved SDK location instead of independently choosing from raw device, app, cache, or backend state.

Backend-Authoritative vs Display-Only

Backend-authoritative sources are allowed to create new backend-facing SOS or telemetry location payloads when they are fresh and valid:

• remoteRelayDevice, for the remote relay event only.
• connectedDevice, for the currently connected own BLE device.
• phone, when used as fallback.

Display-only sources may be shown for continuity or historical context, but must not be used as new backend-authoritative location:

• cachedFallback
• backendSnapshot

backendSnapshot is useful when rendering an existing incident that already has a stored position. It is not a source for creating a new incident or publishing new telemetry.

Telemetry Publishing

Backend telemetry publishing goes through the SDK resolver. This keeps telemetry aligned with SOS and PRE-SOS/DMP location behavior:

• A fresh, valid connected-device GPS fix is preferred.
• Phone/app GPS is used when connected-device GPS is missing, stale, or invalid.
• Remote/relay payload location is used only for the remote event that supplied it.
• Cached fallback and backend snapshot locations are display-only.

Raw Telemetry Guardrails

publishTelemetry(payload) remains available for manually built public payloads, but partner code should not use it to bypass resolver behavior.

Do not publish raw telemetry from:

• cached fallback coordinates
• backend incident snapshots
• remote relay coordinates outside their own relay event
• stale or invalid device samples
• coordinates that are not finite, are outside valid latitude/longitude ranges, or are 0,0

:::warning Known limitation Manually built public telemetry payloads that include app identity and valid coordinates cannot yet prove that the SDK resolver was used. Treat manual payload construction as an advanced compatibility surface and prefer SDK-resolved publishing paths as they become available. :::

Android Foreground and Protection Handoff

Android foreground services and Protection Mode only accept a native handoff when the SDK can provide a fresh, valid, backend-authoritative resolved location, or when Android native code has a fresh OS phone location.

The handoff rules are:

• The sample must be within the accepted TTL.
• Latitude and longitude must be finite numbers.
• Latitude must be in range -90..90; longitude must be in range -180..180.
• 0,0 is rejected.
• SDK handoff samples must be backend-authoritative.
• SDK handoff samples must come from connectedDevice or phone.
• cachedFallback, backendSnapshot, and remote relay samples are not accepted for local Android foreground/protection handoff.
• Native decoder entries include versioning so stale or incompatible persisted handoff entries are rejected instead of reused.

These rules keep Android background behavior aligned with SDK publishing authority and prevent display-only state from becoming operational location.

BLE geoMeta_v2 Decoder Fix

BLE TEL/SOS location decoding now follows the firmware geoMeta_v2 metadata format. This corrects earlier behavior that interpreted the location fields with the wrong packed little-endian layout.

At partner integration level, the important behavior is:

• Connected-device GPS can be trusted as the preferred source only after it decodes into a fresh, valid SDK location.
• Invalid, stale, or out-of-range BLE-derived coordinates are rejected by the resolver and Android handoff guardrails.
• Low-level packet layout details remain firmware/SDK implementation detail and should not be duplicated in partner-facing KB material.

Recommended Backlog

Recommended API follow-up:

• Deprecate manual publishTelemetry(payload) for normal partner use.
• Introduce publishCurrentTelemetry() or publishResolvedTelemetry() so apps can explicitly request resolver-backed telemetry publish.
• Expose a typed telemetry preview model with source, freshness, and backend-authoritative fields for UI and diagnostics.