Turn Mergin Maps Position Tracking On or Off

Writes the three QGIS project properties that enable tracking. Surgical xml2, in the same family as rfp_qgs_theme_set() and rfp_project_settings_apply() - it never re-saves the project through QGIS, so the file's version attribute is preserved.

Usage

rfp_qgs_tracking_set(
  qgs,
  enabled = TRUE,
  frequency = c("normal", "best", "low"),
  layer_id = NULL,
  backup = TRUE
)

Arguments

qgs

Character. Path to the .qgs.

enabled

Logical. Default TRUE.

frequency

One of "normal" (default), "best", "low".

layer_id

Character. The tracking layer's QGIS id. NULL (default) finds it by datasource in the project.

backup

Logical. Write <qgs>.bak first. Default TRUE.

Value

Invisibly, a named character of the three values written.

All three properties, or none

Mergin/PositionTracking/TrackingLayer holds a QGIS layer id, so enabling tracking without a layer produces a project that says it is recording and points at nothing. This writes all three together and refuses when the layer is absent, rather than leaving that state reachable.

The pairing is why the keys are not in inst/lookups/rfp_project_settings.csv: that file holds fleet defaults, and a per-project layer id cannot be one.

frequency is an enum, and each platform reads it differently

There is no settable interval. The three-way enum means different things on different devices, and none of it is documented - it is only in the app source, so it can change between releases without notice:

	Android	iOS	Desktop
"best"	1 m and 1 s	1 m	1 s
"normal"	5 m and 3 s	5 m	2 s
"low"	20 m and 10 s	10 m	5 s

iOS is distance-only - it has no time component, so a stationary phone records nothing at any setting. The same project therefore yields different track densities on different devices.

Two field failure modes worth designing around

• A crash before Stop loses the whole session. Nothing is written until the user taps Stop (mobile#3555).

• Android stops recording with the screen off (mobile#4588), and breaks entirely if app notifications are disabled, since it runs as a foreground service (mobile#3828).

See also

Other tracking: rfp_qgs_tracking_add(), rfp_qgs_tracking_fields_add(), rfp_qgs_tracking_get(), rfp_tracking_fields_add(), rfp_tracking_layer_create()

Examples

if (FALSE) { # \dontrun{
rfp_qgs_tracking_set("~/Projects/gis/my_project/my_project.qgs",
                     frequency = "best")
} # }