[ajgray2017]

Problem

On battery companions the GPS is either powered all the time or off. Meshtastic users expect an interval mode: wake, get a fix, power down, repeat. Nodes that rarely move save a lot of battery this way.

Change

• New sensor setting gps_duty: seconds between fixes, 0 = always on (the default), max 86400. It uses the existing CMD_GET/SET_CUSTOM_VAR, so there is no protocol change.
• Opt-in: listed only after the firmware calls EnvironmentSensorManager::configureGPSDuty(). The companion calls it because it saves the value. Repeater and room server firmware don't list it, so sensor set can't create an unsaved setting there.
• While GPS is on and gps_duty > 0, EnvironmentSensorManager::loop():
  1. powers the GPS on and waits for a fix;
  2. holds the fix GPS_DUTY_SETTLE_SECS (default 10 s) so the RTC can sync;
  3. stores the position and powers the GPS off;
  4. waits gps_duty seconds before the next wake.
• The NMEA parser doesn't run while the GPS is off. It still holds the last fix, and running it would let the periodic RTC resync set the clock back to that fix's time.
• gps_active stays true while the GPS is off, so the gps setting, adverts and telemetry keep using the last fix. Setting gps_duty=0 while asleep powers the GPS straight back on.
• With gps_duty=0, behaviour is the same as before. The parser clear and RTC re-sync on wake only happen when cycling.
• Saved in NodePrefs (gps.duty) and re-applied in applyGpsPrefs().
• OLED GPS page:
  • It shows gps on 5m, or gps sleep 5m while the GPS is off.
  • Long-press on the GPS page now steps through off → on → 1m → 5m → 15m → 1h → off.
  • Boards without gps_duty keep the old toggle, and the sensors page keeps the plain toggle.
• Optional GPS_DUTY_MAX_ON_SECS gives up without a fix (default 0 = wait for a fix).
• Not applied to RAK WisBlock GPS boards, which have their own power handling.
• FAQ entry 5.17. It notes that boards with no GPS power switch save no power; the setting only limits how often the position updates.

Testing

Heltec V3 companion, u-blox module powered from a GPIO enable pin (GPIO42):

• Bounds: gps_duty=-5 and gps_duty=90000 are rejected. 60 and 300 are accepted and persist across a reboot.

• No fix, indoors (debug build, GPS_DUTY_MAX_ON_SECS=45, gps_duty=60): no fix, sleeping 45 s after power-on, then waking 60.0 s later, repeating.

• gps_duty=0 while asleep: NMEA output resumes 0.2 s later and the GPS stays on (no sleep for 60 s). Setting 60 again resumes cycling.

• Repeater with the same GPS: sensor list shows only gps, and sensor set gps_duty 60 replies can't find custom var.

• Unit tests: pio test -e native -e native_kiss_modem passes (54/54).

• Cycle with a fix (gps_duty=300, indoors near a window): fix, power down, wake 300.0 s later, new fix (541 s cold start), power down.

• RTC during sleep, original vs. this PR. Test-only build with the provider's resync interval cut from 30 min to 120 s so the bug shows within one sleep. The clock was checked against the host:

  	at fix	150 s into sleep	270 s into sleep
  parser left running while asleep (first version)	−1 s	−114 s	−234 s
  this PR	0 s	0 s	0 s

  With the parser running, each resync put the clock back to the last fix's time. With the stock 30 min interval and the 1h preset, this sets the clock back by up to an hour.

• OLED: long-press on the GPS page steps through the presets (checked by hand).

• Boards: the fix and RTC tests ran on a second Heltec V3 with the same wiring. The other tests ran on the first board.

Compile-checked (all build, no new warnings; wio_wm1110_repeater shows the same 5 ENV_INCLUDE_GPS redefined warnings as dev):
Heltec_v3_companion_radio_usb, Heltec_v3_companion_radio_ble, Heltec_v3_repeater, Heltec_v3_room_server,
Heltec_t114_companion_radio_ble, Heltec_Wireless_Tracker_companion_radio_ble, Tbeam_SX1276_companion_radio_ble,
Tbeam_SX1276_repeater, LilyGo_TDeck_companion_radio_ble, RAK_4631_companion_radio_ble, RAK_4631_companion_radio_ethernet,
RAK_4631_repeater, RAK_4631_repeater_ethernet, RAK_4631_room_server, RAK_4631_room_server_ethernet,
PicoW_repeater, wio-e5-mini_repeater, LilyGo_Tlora_C6_repeater_, wio_wm1110_repeater.

Open questions for maintainers

1. Is it OK for the GPS-page long-press to cycle presets instead of a pure on/off toggle?
2. Should GPS_DUTY_MAX_ON_SECS default to a timeout (e.g. 300 s), so the GPS doesn't drain the battery indoors waiting for a fix?

Note

This is independent of #3683 (runtime GPS pins) and branches from dev. Both touch the GPS settings list, GPSPrefs and the FAQ numbering. I test-merged the two: the conflicts are "keep both sides", plus one shared #if block in the header and the FAQ renumbered to 5.18. The result runs on a Heltec V3 with all six GPS settings working.

🤖 Generated with Claude Code

[fdlamotte]

Totally agree with you, and we have had several attempts to implement duty cycle but sadly we didn't merge it lacking time to test on all boards ...

I think the first step is to merge #1799 don't know if it will happen with this PR (because it is old and should have been taken care of sooner), but I want a clean frontier between LocationManager and EnvironmentSensors and things have not gone in the good way lately ...

Then, when things are clearer we'll implement duty cycle in LocationManager and add cli commands to control it

You're proposal is interesting but I prefer when we go small steps (and in first steps I don't see why we would make changes to the UI). Also we can use AI, but don't let it do everything as it seems to be the case with this PR.

[AlexandrTyshchenko]

Thanks for this — we run a similar GPS duty cycle on a solar repeater (ProMicro + serial GNSS with EN pin) and can share some field notes:

• GPS_DUTY_MAX_ON_SECS default: we started at 120 s and had to raise it to 300 s. With the module's power fully cut between fixes it effectively cold-starts each time, and 120 s was often not enough. 300 s seems a sensible default; 0 (wait forever) can drain a battery when the sky view is poor.
• Stale fix on wake: we call nmea.clear() when powering the GPS back on. Otherwise isValid() and the old position/time from the previous window remain visible until the first new sentence arrives, and the settle timer can count against old data.
• Repeaters/sensors: solar repeaters are where this saves the most power. Would you consider exposing gps_duty in the repeater and sensor firmware too (stored in their prefs), not only companion?

We're also proposing a GPS anti-spoofing guard (#3733) that hooks into the same loop(); happy to build it on top of this PR.

[ajgray2017]

Thanks for this — we run a similar GPS duty cycle on a solar repeater (ProMicro + serial GNSS with EN pin) and can share some field notes:

• GPS_DUTY_MAX_ON_SECS default: we started at 120 s and had to raise it to 300 s. With the module's power fully cut between fixes it effectively cold-starts each time, and 120 s was often not enough. 300 s seems a sensible default; 0 (wait forever) can drain a battery when the sky view is poor.
• Stale fix on wake: we call nmea.clear() when powering the GPS back on. Otherwise isValid() and the old position/time from the previous window remain visible until the first new sentence arrives, and the settle timer can count against old data.
• Repeaters/sensors: solar repeaters are where this saves the most power. Would you consider exposing gps_duty in the repeater and sensor firmware too (stored in their prefs), not only companion?

We're also proposing a GPS anti-spoofing guard (#3733) that hooks into the same loop(); happy to build it on top of this PR.

Take whatever youd like! i wrote this for myself, since the little heltec v3's I built didnt have huge batteries. @AlexandrTyshchenko

[AlexandrTyshchenko]

Thanks @ajgray2017, much appreciated! My duty cycle lives in the repeater build for now, so it's good to see the same approach working on a companion.

Per @fdlamotte's comment I'll wait for #1799 and then propose duty cycling as small steps on top of LocationProvider, with the repeater/sensor case in mind. Your RTC-resync finding (stopping the parser while the GPS is off) is a good catch and I'll make sure to keep it.

[fdlamotte]

I might not wait for #1799 after all ...

Hope to find time next week to refactor GPS, would like a clean interface for all the roles to use it and configure via cli

then adding duty_cycle is easy

#778 was close to what I wanted but we didn't finish it (and for some time back then I couldn't work on meshcore due to other things)

[AlexandrTyshchenko]

Sounds good, @fdlamotte. A clean GPS interface shared by all roles is exactly what I was missing on the repeater side.

Two small things it would help to leave room for, so I can port my PRs onto it instead of hooking into EnvironmentSensorManager:

• A fix filter hook: a way to reject a fix before it's used for position or adverts (sats/HDOP, plus a region or jump check). This is what GPS: optional anti-spoofing guard for position and time (GPS_GUARD) #3736 (GPS_GUARD) needs; spoofing is a real problem where my nodes run.
• A time-sync gate: the RTC sync from GPS going through one place that can say no. GPS: optional anti-spoofing guard for position and time (GPS_GUARD) #3736 uses it to refuse spoofed time, and it also covers the stale-time issue @ajgray2017 found while the GPS is powered down.

#3729 (UART baud autodetect) would fit naturally into the NMEA provider's start-up. Happy to test the refactor on a ProMicro repeater with a serial GNSS (EN pin) and duty cycling, and to rebase both PRs once it lands.

[fdlamotte]

it's nice to have some discussion about this before doing the implementation task

on the separation between LP and ESM, after reading #778 one of the key factor of this separation is to bring GpsDriver ... I think the reason why things got pushed to ESM is because LP is seen as the driver and ESM the managerm where for GPS, LP should be the manager (and should report only the values to ESM), so we need a driver to talk to ;) (If I recall well, this is what we had come to when discussing this with @awolden )

I will open a PR as soon as I have the first bits working so people can discuss which direction to go to ...

[AlexandrTyshchenko]

Makes sense to me - LP as the GPS manager with a GpsDriver underneath is a cleaner split than what we have now, and it maps well onto my PRs:

• the fix filter and the time-sync gate from GPS: optional anti-spoofing guard for position and time (GPS_GUARD) #3736 are manager logic, so they'd sit in LP before values are reported to ESM;
• the UART baud autodetect from GPS: optional UART baud rate autodetection (GPS_BAUD_AUTODETECT) #3729 is driver-level and would move into GpsDriver start-up.

I'll hold off on rebasing until your first PR is up, then port both onto it and test on a ProMicro repeater with a serial GNSS (EN pin) and duty cycling.

[fdlamotte]

Refactor of the GPS has now been done ... and it covers the aim of this PR

Thanks for proposing that again .. that made me move to concretize what I had in mind for a long time