Presets & overrides

Beekon ships three battery presets. They’re the only signal-processing knobs in v1 — there’s no Kalman filter, no outlier rejection, no speed clamp. The OS provider is the source of truth.

Preset	Distance filter	Interval	Battery	Use case
Saver	150 m	60 s	3–8 %	Passive background tracking
Balanced (default)	100 m	30 s	5–10 %	General tracking
Precision	30 m	10 s	15–25 %	Active foreground use

The numbers are identical on every platform. A position must satisfy both the interval and distance gates before Beekon emits it — that’s the whole gate algorithm.

How the gate works

For each fix delivered by the OS provider, Beekon emits the position iff:

(now - lastEmittedTime  >= interval) AND
(distanceFrom(lastEmittedPoint) >= distanceFilter)

The very first fix after start() always passes. After that, both conditions must hold. There’s no minimum-velocity threshold and no maximum-accuracy filter — those would alter raw passthrough.

Why both, not either?

Either-only gates leak: an interval-only gate fires on a stationary device every interval; a distance-only gate fires constantly while in motion regardless of how dense the resulting trail is. The AND-gate hits a useful equilibrium for trail rendering and history queries.

Choosing a preset

Pick by typical user scenario, not by what feels safest:

• Saver is for passive trips you don’t want to drain the battery. The trail will look coarser; that’s fine for “where did I go today” overlays.
• Balanced is the right default for almost everything — driving, cycling, multi-hour walks.
• Precision is foreground-only on real devices. Don’t ship a background app on Precision; users will notice the battery hit.

Custom overrides

You can override either the interval or distance (or both) without leaving a preset. The override fully replaces the preset’s value for that field — it’s not multiplied or capped.

Android

// 5-second cadence on Balanced (faster than Balanced default 30s)
Beekon.configure(
  BeekonConfig(
    preset = Preset.Balanced,
    intervalMillis = 5_000,
    notification = notification,
  ),
)

// Or push to 250m distance only
Beekon.configure(
  BeekonConfig(
    preset = Preset.Balanced,
    distanceFilterMeters = 250f,
    notification = notification,
  ),
)

iOS

// 5-second cadence on Balanced
await Beekon.shared.configure(
  BeekonConfig(preset: .balanced, intervalSeconds: 5)
)

// 250m distance only
await Beekon.shared.configure(
  BeekonConfig(preset: .balanced, distanceFilterMeters: 250)
)

Flutter

// 5-second cadence on Balanced
await Beekon.instance.configure(
  const BeekonConfig(
    preset: BeekonPreset.balanced,
    interval: Duration(seconds: 5),
    androidNotification: notification,
  ),
);

// 250m distance only
await Beekon.instance.configure(
  const BeekonConfig(
    preset: BeekonPreset.balanced,
    distanceFilterMeters: 250,
    androidNotification: notification,
  ),
);

The Flutter API takes a Duration for ergonomics; on the wire it travels as intervalMillis. Native APIs use Long intervalMillis (Android idiom) and Double intervalSeconds (Swift’s TimeInterval).

Changing preset at runtime

Calling configure(...) again replaces the active config — including the preset and overrides. The new values take effect on the next start(). If you’re already tracking, call stop() then start() for the change to apply to the live pipeline.

configure(saver)  ─→  start()   tracking at 60s/150m
configure(precision)  // takes effect on next start()
stop()
start()           ─→  tracking at 10s/30m

What presets do not do

• They don’t bound the OS provider’s accuracy. A position with 50 m accuracy still emits if it passes the gate.
• They don’t smooth the trail. Adjacent emissions can jump if the OS provider’s signal jumps.
• They don’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 Beekon.positions.