owntracks 配置注意事项

pubTopicBase

owntracks/user/8CFADEA9-85DB-4716-B3F1-6C955523F72F

手机向外发布位置时用的 MQTT topic 前缀。所有消息都会追加 /event 或 /info 等后缀。生效条件：连接 MQTT broker 且 app 处于后台或前台。

ignoreStaleLocations days

-1

天数阈值。若本地缓存的位置数据早于该天数，则忽略并重新定位。-1=永不忽略，始终用最新定位；0=始终忽略缓存。生效条件：每次启动或从后台唤醒时。

ignoreInaccurateLocations Meters

空（默认 0）

若位置精度（horizontalAccuracy）大于该值则丢弃。0=不丢弃任何位置；例如填 50 则只保留误差 ≤50 m 的位置。生效条件：每次定位回调。

locatorDisplacement Meters

50

最小位移触发条件：只有当设备移动 ≥50 m 才请求一次新位置。生效条件：Monitoring 模式为 Significant Location Change 或 iOS Region Monitoring 时。

locatorInterval Seconds

5

最小时间触发条件：两次定位请求至少间隔 5 s。配合 locatorDisplacement 形成“或”关系。生效条件同上。

positions

15

本地缓存的最大位置点数。超过后最旧记录被自动删除。生效条件：应用运行期间，每次写入新的位置记录。

days

-1

与 ignoreStaleLocations 同义，旧 UI 保留字段；若两者同时存在，以 ignoreStaleLocations 为准。

pubQos

1

MQTT 发布质量等级。0=最多一次（不确认），1=至少一次（可能重复），2=恰好一次（最可靠）。生效条件：每次向 broker 发送消息。

monitoring

0

全局开关。0=关闭自动发布；1=Significant Location Change；2=Move Mode（高频率）；3=Quiet（手动）。生效条件：App 启动或用户切换模式。

downgrade

0

当 MQTT 连接失败时，1 将自动退回 HTTP 上报；0 保持重试 MQTT。生效条件：首次连接失败或网络恢复时。

adapt

0

动态调整定位频率。1=根据电池、速度自动降低频率；0=始终按 locatorInterval/displacement 设定。生效条件：Monitoring ≥1 时。

ranging

空（未启用）

iBeacon 近场扫描开关。开启后，当进入/离开 iBeacon 区域会生成额外的 transition 事件。生效条件：Monitoring ≥1 且手机支持 BLE。

locked

空（未启用）

强制后台定位权限提示。1=即使系统已授予也会再次弹窗，用于调试。生效条件：仅在调试构建中可用。

pubRetain

空（未启用）

MQTT Retain 标志。1=broker 保留最后一条位置消息，供新订阅者立刻获取；0=不保留。生效条件：每次 publish。

Map / Friends / Regions

UI 入口

非配置项，仅界面导航。Map 显示当前位置；Friends 列出共享的好友；Regions 管理地理围栏。