Tuning the gate

BeekonConfig has exactly two scalars — a minimum time interval between emitted fixes and a minimum distance. They form an AND-gate: a position is emitted only when both conditions are satisfied. That’s the entire signal-processing surface in v1 — no Kalman filter, no outlier rejection, no speed clamp. The OS provider is the source of truth.

Field	Default	Disable
intervalSeconds	30	0
distanceMeters	100	0

The defaults (30 s / 100 m) are a balanced battery / density trade-off — fine for general-purpose tracking. Same on every platform.

How the gate works

For each fix the OS provider delivers, Beekon admits it iff:

(now - lastAdmittedTime    >= intervalSeconds) AND
(distance(lastAdmittedFix) >= distanceMeters)

The very first fix after start() always passes. After that, both conditions must hold. Set either field to 0 to disable that side of the gate — intervalSeconds = 0 admits a fix as soon as the distance threshold is met regardless of cadence; distanceMeters = 0 admits at most one fix per intervalSeconds.

Why AND, not OR?

OR-gates leak: an interval-only gate fires on a stationary device every interval; a distance-only gate fires constantly while in motion regardless of trail density. AND hits a useful equilibrium for trail rendering and history queries.

Picking values

Scenario	intervalSeconds	distanceMeters	Notes
Passive background (“where did I go today?”)	60	150	Coarse trail; cheaper on battery
General tracking (default)	30	100	Driving, cycling, multi-hour walks
Active foreground (turn-by-turn, fitness)	5–10	25–50	Foreground-only on real devices; users feel the battery hit in background
Stationary monitoring (geofence-like)	0	100	Emit only on movement, not on cadence

These are starting points, not presets — calibrate against your own GPX corpus.

Live tuning

Call configure(...) again at any time, including while tracking, to update the gate. The new values take effect on the next admitted fix without restarting the underlying location subscription.

Android

// Tighten cadence mid-session
Beekon.configure(
  BeekonConfig(intervalSeconds = 5, distanceMeters = 25.0, notification = notification),
)

iOS

await Beekon.shared.configure(
  BeekonConfig(intervalSeconds: 5, distanceMeters: 25)
)

Flutter

await Beekon.instance.configure(
  const BeekonConfig(
    intervalSeconds: 5,
    distanceMeters: 25,
    androidNotification: notification,
  ),
);

React Native

await Beekon.configure({
  intervalSeconds: 5,
  distanceMeters: 25,
  androidNotification,
});

What the gate does not do

• It doesn’t bound the OS provider’s accuracy. A fix with 50 m horizontal accuracy still emits if it passes the gate.
• It doesn’t smooth the trail. Adjacent emissions can jump if the OS provider’s signal jumps.
• It doesn’t alter the persistence schema or retention — see Persistence & history.

To filter on accuracy or smooth the trail, do it in your own code on top of the live stream.