GPS Tracking

This document describes how GPS telemetry works for companion/client nodes and sensor nodes.

Scope

GPS tracking uses the existing CayenneLPP GPS telemetry field. It does not add a new phone app protocol field.

The GPS telemetry value contains latitude, longitude, and altitude. Speed, heading, and freshness are not sent as separate telemetry fields.

If the firmware does not have a valid fresh GPS cache, it omits the GPS field from telemetry. This is intentional: stale or missing fixes are not reported as zero coordinates.

Freshness

GPS telemetry is cached separately from advert location.

The cache behavior is:

Refresh the cached GPS value every 2 hours only when at least one contact or ACL client can receive location telemetry.
Try for up to 15 minutes during a refresh.
If the position stays within about 100 meters for 30 seconds, cache a weighted average of the stable fixes, with newer fixes weighted more heavily.
If the position moves outside that 100 meter circle during acquisition, cache the latest valid fix.
Omit GPS from telemetry if there is no fix or if the cached fix is more than 12 hours old.

When a telemetry request asks for location, GPS is normally kept on for 2 hours after the latest location request. During that hold window, later location telemetry requests can use fresh GPS data as soon as valid fixes are available.

If GPS is manually enabled, it stays on and valid fixes continue to update the cache.

If no contact or ACL client can receive location telemetry, the scheduled 2-hour refresh does not run. A real location telemetry request can still turn GPS on, and manual GPS-on still keeps the cache updated.

Repeater Nodes

Repeaters use a shorter on-demand policy when GPS is manually off. An authorized location-telemetry request wakes the receiver only when its cached position is stale. The first valid fix is cached and GPS processing immediately stops; the next request can return that fix without another wake. gps off also cancels an acquisition already in progress. An acquisition that never obtains a fix retains the normal 15-minute safety timeout. Physical supply switching depends on the board and its shared peripheral policy.

When GPS and device power saving are both enabled, a repeater wakes GPS for up to 10 minutes to obtain a valid time and then sleeps it for seven days. A valid GPS time may correct the RTC either forward or backward. With device power saving off, an enabled GPS remains active and refreshes the RTC every 30 minutes.

RAK WisBlock Power Supply

RAK4631 defaults to saved peripheral mode gps-only. With no protected power owner, stopping or sleeping GPS can turn off the shared 3V3_S rail. If other attached modules need that rail, explicitly select shared mode:

get peripherals.mode
set peripherals.mode shared
reboot

Use set peripherals.mode gps-only and reboot to return to the default. Changes are saved for the next boot, not applied live; the query reports the saved choice. Other peripheral requirements are not guessed from an I2C scan. Boot and discovery keep the rail on until the power policy is established.

This saved setting is available in Companion and Common CLI roles (repeater, room server, and sensor). Raw KISS and legacy Terminal Chat do not configure it and retain the powered rail. Shared mode controls the supply; it does not add Ethernet support to a non-Ethernet firmware target.

Ethernet/PoE builds and detected external NOR storage automatically retain power regardless of this setting. RAK3401 always retains the rail for its radio frontend and does not offer this override.

In shared mode, GPS-off does not mean the supply is off. In particular, the RAK12501/L76K module has no independent power switch: stopping MCU parsing leaves the receiver powered. Internal sleep support on other GNSS modules is receiver-dependent. This setting does not remove the UART1 bridge conflict or authorize another transmitter on the GPS wiring.

Companion/Client Nodes

Companion/client telemetry uses the existing companion telemetry permission system:

base telemetry
location telemetry
environment telemetry

Location telemetry is sent only when the requester's effective telemetry permissions include location. Those permissions are derived from the companion telemetry mode settings and contact flags.

No new phone app behavior is required. Existing clients see the existing GPS telemetry field when it is present.

The scheduled GPS cache refresh runs only when at least one stored contact has effective location telemetry access:

location: allow all with at least one stored contact
location: allow flags with at least one stored contact whose flags include location

Sensor Nodes

Sensor telemetry access is controlled by:

get telemetry.access
set telemetry.access all
set telemetry.access acl

all is the default and matches the previous sensor telemetry behavior. A request that reaches the normal sensor telemetry request path can receive the requested telemetry fields, including GPS, subject to the request mask and GPS freshness rules.

acl gates telemetry through the sensor ACL. A requester with read-only or higher permissions receives the existing telemetry set, including GPS. Guest or unknown requesters receive no telemetry fields.

The scheduled GPS cache refresh follows the same access setting:

all: runs only when at least one ACL client exists
acl: runs only when at least one ACL client is read-only or higher

Use the existing ACL command to grant access:

setperm <pubkey> 1

Permission values:

1: read-only, suitable for telemetry access
2: read-write
3: admin

Advert location is separate from telemetry GPS. The advert policy is controlled with:

gps advert
gps advert none
gps advert share
gps advert prefs

Policies:

none: do not include location in adverts
share: use the live/shared sensor manager location
prefs: use the stored node latitude and longitude preferences

prefs is the first-boot default for every repeater, room-server, and sensor build. Firmware updates retain an explicitly saved policy from the existing preferences filesystem.

Telemetry GPS can be fresh while advert location is fixed or disabled, depending on this policy.

Recommended Setup

For private sensor tracking:

set telemetry.access acl
setperm <owner_pubkey> 3
setperm <trusted_pubkey> 1

For compatibility with the older sensor behavior:

set telemetry.access all

For GPS telemetry behavior, leave the phone app unchanged. The firmware omits GPS when it is stale or missing and sends the existing GPS telemetry field when fresh data is available.