201 lines
6.9 KiB
Markdown
201 lines
6.9 KiB
Markdown
<!-- meshcore-hosted-doc-link:start -->
|
|
<p class="meshcore-hosted-doc-link"><a href="https://mikecarper.github.io/MeshCore/gps_tracking/">View this page on MeshCore Docs</a>.</p>
|
|
<!-- meshcore-hosted-doc-link:end -->
|
|
|
|
# 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:
|
|
|
|
```text
|
|
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](https://docs.rakwireless.com/product-categories/wisblock/rak12501/datasheet/)
|
|
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:
|
|
|
|
```text
|
|
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:
|
|
|
|
```text
|
|
setperm <pubkey> 1
|
|
```
|
|
|
|
Permission values:
|
|
|
|
- `1`: read-only, suitable for telemetry access
|
|
- `2`: read-write
|
|
- `3`: admin
|
|
|
|
## Advert Location
|
|
|
|
Advert location is separate from telemetry GPS. The advert policy is controlled
|
|
with:
|
|
|
|
```text
|
|
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:
|
|
|
|
```text
|
|
set telemetry.access acl
|
|
setperm <owner_pubkey> 3
|
|
setperm <trusted_pubkey> 1
|
|
```
|
|
|
|
For compatibility with the older sensor behavior:
|
|
|
|
```text
|
|
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.
|