Skip to content

Big GPS refactor - #3753

Merged
fdlamotte merged 25 commits into
meshcore-dev:devfrom
fdlamotte:gps_refactor
Nov 10, 2026
Merged

fdlamotte merged 25 commits into
meshcore-dev:devfrom
fdlamotte:gps_refactor

Conversation

@fdlamotte

Copy link
Copy Markdown
Collaborator

Following #3684 I'll work here on refactoring GPS management

The idea is to keep LocationProvider as the interface to the loop, but adding GpsDriver class to manage low-level things

I also tried to pull all i2c RAK GPS related things out of EnvironmentSensorManager ... this was huge and I hope I didn't do any mistake as I don't have i2c rak gps ... if someone can help me with testing ...

periodic wakeup has been added, and a command is available for the repeater CLI, will make a GPSPrefs class to share gps command between repeater and companion

Still a long way to go (as I've seen lots of bad things in current code with active waits on gps frames for instance !)

@cwichura

cwichura commented Nov 2, 2026

Copy link
Copy Markdown

This is exciting to see. Please make sure to factor in the NMEA auto-baud selection from #3729. This fixes GROVE GPS modules from M5Stack, for example. And it would also be good to fold in #3736.

Also, does the common virtual API of the base class facilitate devices like the Thinknode M1 that have a physical on/off switch that relies on the firmware to actually disable/enable the GPS (as opposed to a switch that physically disconnects power from the GPS module)?

@fdlamotte

fdlamotte commented Nov 2, 2026 •

Copy link
Copy Markdown
Collaborator Author

This is exciting to see. Please make sure to factor in the NMEA auto-baud selection from #3729. This fixes GROVE GPS modules from M5Stack, for example. And it would also be good to fold in #3736.

Yes, #3729 can easily be implemented in GpsDriver, I think #3736 would better sit in LocationProvider

Also, does the common virtual API of the base class facilitate devices like the Thinknode M1 that have a physical on/off switch that relies on the firmware to actually disable/enable the GPS (as opposed to a switch that physically disconnects power from the GPS module)?

Are you sure the physical button on M1 is not an hw switch as on M5 ?

I've just refactored both to use the same path (because if switch is HW there is no need to poll) but your comment make me think maybe I'm wrong (and I still don't have the M1 to test that)

edit: I have confirmation the switch is purely software on M1 ... too bad. I should probably take care of sw gps switch in the driver then (to keep coherent with the gps state)

@cwichura

cwichura commented Nov 2, 2026

Copy link
Copy Markdown

I own a v1 M1. The switch is just a GPIO input; it does not physically disconnect/power down the GPS module in the M1.

@fdlamotte

fdlamotte commented Nov 2, 2026 •

Copy link
Copy Markdown
Collaborator Author

Ok, the refactoring has been ported to all ports.

I think I now need some feedbacks on what I possibly have broken ;)

I'm doing tests on my side with what I have ...

The feedback I'd need would be on:

  • any RAK board with i2c gps
  • Nano G2 Ultra
  • MeshTracker X1
  • Heltec Tracker
  • both Muzi SuperIO radios
  • ThinkNode M1
  • Heltec Mesh Solar
  • MeshAdventurer

I've notice a build issue with meshsolar companions, this predates this PR (also happens in dev)

@cwichura

cwichura commented Nov 4, 2026

Copy link
Copy Markdown

I just saw #3760 got opened, which suggests it too has a software GPS switch. (I don't own this hardware, so can't check, myself.)

@IoTThinks

Copy link
Copy Markdown
Contributor

Look like the new GPS module is coming.
Great.

@fdlamotte

Copy link
Copy Markdown
Collaborator Author

I just checked the rak serial nmea gps path using a modified variant using rak classes and it works

Still need some input from people using rak with i2c gps module

@nGoline

nGoline commented Nov 4, 2026

Copy link
Copy Markdown

Tested on a Muzi Base Uno + SuperIO, following up on #3760.

As-is, the Muzi GPS gets no data: the refactor no longer calls Serial1.setPins() on nRF52, and the Muzi variant.h had PIN_SERIAL1_RX/TX swapped (main only worked because setPins(PIN_GPS_TX, PIN_GPS_RX) swapped them back). Any other nRF52 variant whose PIN_SERIAL1_* doesn't match its real GPS wiring will break the same way, so it may be worth a check.

The new switch handling works well: off at boot in the middle position, on at the top, and both the switch and the UI toggle power the GPS down and back up correctly.

PR with the pin fix and the ATGM336H NMEA re-enable on top of your branch: fdlamotte#1

@fdlamotte

Copy link
Copy Markdown
Collaborator Author

Tested on a Muzi Base Uno + SuperIO, following up on #3760.

As-is, the Muzi GPS gets no data: the refactor no longer calls Serial1.setPins() on nRF52, and the Muzi variant.h had PIN_SERIAL1_RX/TX swapped (main only worked because setPins(PIN_GPS_TX, PIN_GPS_RX) swapped them back). Any other nRF52 variant whose PIN_SERIAL1_* doesn't match its real GPS wiring will break the same way, so it may be worth a check.

The new switch handling works well: off at boot in the middle position, on at the top, and both the switch and the UI toggle power the GPS down and back up correctly.

PR with the pin fix and the ATGM336H NMEA re-enable on top of your branch: fdlamotte#1

Thank you very much ...

So I'll check for lost assignations I could have missed in the process ;)

@fdlamotte

Copy link
Copy Markdown
Collaborator Author

I'm restoring setPins

Think I found some way to simplify things too

@fdlamotte fdlamotte changed the title WIP: GPS refactor Big GPS refactor Nov 5, 2026
@fdlamotte

Copy link
Copy Markdown
Collaborator Author

just thought about a gps once command ...

think it's interesting to be able to sync position manually

@cwichura

cwichura commented Nov 6, 2026 •

Copy link
Copy Markdown

just thought about a gps once command ...

Doesn't the gps setloc command already provide that functionality?

It occurs to me, pulling in the GPS blurring via precision truncation from #2611 would make sense in this refactoring.

@fdlamotte

fdlamotte commented Nov 6, 2026 •

Copy link
Copy Markdown
Collaborator Author

just thought about a gps once command ...

Doesn't the gps setloc command already provide that functionality?

gps setloc was only to copy position from gps to the prefs (which can be different), and it's on the repeater (where advert can be set to gps/prefs/none. It does not trigger a fix

What I'm wondering is if the gps sync command wouldn't already be good for that, instead of adding a new command ... in some cases gps sync already changes position as a side effect, so It might be better to have this behaviour always.

It occurs to me, pulling in the GPS blurring via precision truncation from #2611 would make sense in this refactoring.

I'd better let the author rebase against refactor when this is done ...

I'll do a tour around all pending prs regarding gps to call for rebase

edit: turns out I was probably wrong about sync as it does not seem to wake gps ... it seems only to set a flag so clock is synced with gps at next fix ... if it's too complicated there must be an issue here ;) will try to rationalize things and I might introduce once to make a unique acquisition, and once -s to do the sync at the same time

@Ve2mrx

Ve2mrx commented Nov 7, 2026

Copy link
Copy Markdown

Tested 0388403b on a RAK WisMesh Repeater Mini v2 (RAK4631, RAK19007, RAK12501 serial L76K, no other slot modules), since you asked for RAK feedback.

The serial path works: it gets a fix and sets the clock. But on this hardware gps off, periodic mode and shutdown leave the GPS powered:

State This PR v1.18.0 with rail control
gps on 40.3 to 40.8 mA 40.0 to 40.2 mA
gps off 40.2 to 40.8 mA 11.4 to 12.4 mA
gps period 60, while waiting 40.9 mA not applicable
shutdown 29.7 mA 1.22 mA

ChargerLAB KM003C in line on USB at about 5.11 V, battery and panel disconnected, powersaving on, medians over 20 s or more.

On rak4631, RakLocationProvider builds _nmeaDriver(serial) with PIN_GPS_EN=-1 and no peripheralPower, so stopHardware() has no pin to drive. The RAK12501's power comes from 3V3_S, which WB_IO2 switches on the RAK19007.

Would you take rail control for this case on top of this PR? NmeaGpsDriver already accepts peripheralPower, so it may be small. I assume it has to be opt-in, because WB_IO2 also powers other slot modules.

Who did what: I worked on this with Claude Code. I set the requirements, built the bench setup and flashed the builds. Claude wrote the patch, read this PR and the RAK schematics, scripted the commands and meter readings, and drafted this comment, which I reviewed before posting.

@fdlamotte
fdlamotte force-pushed the gps_refactor branch 3 times, most recently from fbfbe0f to 2ed1973 Compare November 8, 2026 00:14
@fdlamotte

Copy link
Copy Markdown
Collaborator Author

The serial path works: it gets a fix and sets the clock. But on this hardware gps off, periodic mode and shutdown leave the GPS powered:

Thanks, I tested the path (using the rak location manager) on non rak hw, but testing it with rak is nice

Would you take rail control for this case on top of this PR? NmeaGpsDriver already accepts peripheralPower, so it may be small. I assume it has to be opt-in, because WB_IO2 also powers other slot modules.

Please make a PR over my gps_refactor branch: https://github.com/fdlamotte/MeshCore/tree/gps_refactor

And tag me in so I see it. I'll be glad to add it since it is something that is needed.

Do the same rail control apply for i2c gps ? If not, please take care that it only applies on the nmea path

@fdlamotte
fdlamotte merged commit 62ae611 into meshcore-dev:dev Nov 10, 2026
15 checks passed
marcelverdult added a commit to marcelverdult/MeshCore_Refactor that referenced this pull request Nov 10, 2026
marcelverdult added a commit to marcelverdult/MeshCore_Refactor that referenced this pull request Nov 10, 2026
docs: re-plan cut E2 on the GPS shape after upstream meshcore-dev#3753
@Avamander

Copy link
Copy Markdown
Contributor

Was it considered to wait for a proper 3D fix before using time and location from a receiver?

It should also be noted that when set to periodically acquire a fix, the receivers don't get a proper chance to receive the full almanac, or ephemerides. Which makes finding a solution the next time as slow as a cold start and ensuring a correct fix harder.

There also aren't any checks done that the receivers actually consider their time fix valid (CASIC has NAV-TIMEUTC, UBX and others have similar commands). Which should really be the primary approach over any heuristics.

@AlexandrTyshchenko

Copy link
Copy Markdown

Thanks, good points. On the GPS_GUARD part (my side of this):

  • 3D fix: right, the fix type from GSA is not checked; MicroNMEA doesn't parse GSA. The guard requires ≥4 sats, HDOP ≤ 4.0 and 5 consistent fixes in a row, but that is not the same as the receiver reporting 3D. Adding a GSA fix-mode check to the guard looks cheap, I can do it.
  • Periodic mode: agreed, the receiver is switched off a few seconds after the fix, before it can collect full ephemerides. Whether they survive the sleep depends on backup power on the module. A configurable minimum on-time after the fix (e.g. 30–60 s) would help hot starts; I'd measure TTF on our board before proposing a default.
  • Receiver time validity: agreed it should be used where available (UBX/CASIC NAV-TIMEUTC), but that is vendor binary protocol, so it would live in chip-specific drivers. It doesn't replace the guard though: under spoofing the receiver reports everything as valid (we had a 12-satellite fix ~12 000 km away), so the heuristics are against spoofing, not against receiver uncertainty.

@fdlamotte

Copy link
Copy Markdown
Collaborator Author

The primary goal of the refactor was to get gps management code in a better state.

As duty cycle for gps was something asked for a long time (and I was really upset by the gps-interval thing that had been added, which could make people think this was implemented while it was not) I've proposed a first implementation as part of the refactor (mostly to show where things go)

I think (hope) the way is open to get better solutions for the fix ... I'm really open to that, but I wanted first to fix some things in the code

@IoTThinks

Copy link
Copy Markdown
Contributor

I have had similar implementation for GPS PowerSaving to cut power (not just activate / deactivate) of the GPS.

I guess it will take a few weeks to test this PR.
I have most of the common boards with GPS.

@AlexandrTyshchenko

AlexandrTyshchenko commented Nov 12, 2026 •

Copy link
Copy Markdown

Follow up with numbers, and the 3D check is in #3821.

Time to fix on our Faketec board with a u-blox MAX-M10S breakout (UART, NMEA, EN pin power-gated between fixes):

  • cold start after reboot: ~1 min
  • 5 min period: 7-40 s (4 cycles)
  • 30 min period: 48 s - 1 min (2 cycles)

The breakout has a small backup cell wired to V_BCKP (checked), so the ephemerides survive the off time, and the module mostly does hot/warm starts. I don't plan a minimum on-time for now; modules without backup power will likely need a longer on-time after each wake-up.

One more data point for the receiver-flags question: during the night there was spoofing again, and the receiver reported a 3D fix (GSA mode 3) with 6-7 satellites for a position outside the region. Only the region check rejected it. So the receiver's own validity flags didn't help there.

@fdlamotte

Copy link
Copy Markdown
Collaborator Author

I have had similar implementation for GPS PowerSaving to cut power (not just activate / deactivate) of the GPS.

I guess it will take a few weeks to test this PR. I have most of the common boards with GPS.

Your feedback will be welcome

I felt it was necessary to let the PR in so the new interface is fixed, but I'm sure we'll have some issues on the driver side ...

@marineam

Copy link
Copy Markdown

Just wanted to call out here since folks involved in this PR may have insight into an eventual fix: as noted in #3830 this PR changed the RAK Pocket V3 GPS from being always powered to being always unpowered. Commit df5a768 is where the behavior changed.

@Ve2mrx

Ve2mrx commented Nov 14, 2026

Copy link
Copy Markdown

Field data from a RAK4631 repeater on dev (d495d2ed), since 2026-11-10. It's a RAK WisMesh Repeater Mini v2: RAK19007, RAK12501 (Quectel L76K, serial), env RAK_4631_repeater_gps_power (so WB_IO2 cuts the slot rail between fixes). It runs outdoors on battery and a small panel, with gps period 1d since 2026-11-11.

On the cold-start concern raised above: at a 1-day period each fix takes about as long as the L76K's 30 s cold start, because the ephemerides have expired by then anyway. The fixes are steady, though, and none has failed.

Fix Date (UTC) Off before it Time to fix
1 2026-11-10 about 43 h 33 s (indoors, by a window)
2 2026-11-11 about 24.5 h 30 s
3 2026-11-12 about 24 h 27 s
4 2026-11-13 about 24 h 29 s
5 2026-11-14 about 24 h 35 s

gps fix_stats after fix 5: ttf:35s/35s ok:5 miss:0. Fixes 2 to 5 were taken mounted outside.

On the RAK12501, V_BCKP is fed from the always-on 3V3 through R25, not from the switched 3V3_S. So when WB_IO2 cuts the rail, the L76K drops to its Backup mode (8 µA in the datasheet) and keeps its RTC, almanac, last position and ephemerides. That pays off at short periods. On the bench with gps period 60 and the rail cut between fixes, the last fix took 7 s (ttf:7s/1m ok:7 miss:0). At a 1-day period the saved ephemerides are too old to use, so the module has to download new ones, which takes about 30 s. A minimum on-time after the fix wouldn't help here: whatever it saved would also be out of date a day later. On this module, short periods are already fast thanks to the backup supply. Modules without backup power will behave differently, as noted above.

Cost of the duty cycle on this unit: on battery, with the GPS in waiting (rail off), the whole repeater draws about 4 mA on average over four nights (3.3 to 5 mA each). That's estimated from the overnight voltage drop (about 320 mAh per 100 mV near 4.0 V on its 3200 mAh cell), so it's rough, but it is far below the 40 mA with the GPS left powered.

This build predates #3821 (3D fix), #3823 (first-fix timeout) and #3834 (WB_IO2 after a failed RAK12500 probe). The next build will include them, and I'll report if the 3D requirement changes the times on this module.

Who did what: I worked on this with Claude Code. I set the requirements, mounted the unit and took the first readings in the app (Home Assistant now takes them). Claude logged and analysed the readings and drafted this comment, which I reviewed before posting.

@Ve2mrx

Ve2mrx commented Nov 16, 2026 •

Copy link
Copy Markdown

Follow-up to my comment above, as promised. Since 2026-11-14 the same repeater runs dev at 7f7512d9 (with #3821, #3823 and #3834) plus #3844 and #3845, both now merged. Same env (RAK_4631_repeater_gps_power), gps period 1d.

The next build on this unit will be plain dev.

Who did what: I worked on this with Claude Code. I flashed the builds and ran the tests at the unit; Home Assistant takes the daily readings. Claude analysed the results and drafted this comment, which I reviewed before posting.

@Avamander

Copy link
Copy Markdown
Contributor

@Ve2mrx Did you also try checking vendor-specific commands for time quality before using it? L76K is unfortunately a cheap economy model so it doesn't reveal a lot, nor have a lot of features.

At a 1-day period the saved ephemerides are too old to use, so the module has to download new ones, which takes about 30 s. A minimum on-time after the fix wouldn't help here

Almanac downloads take longer and they stay valid longer. Once acquired and the module doesn't get entirely powered off (backup domain stays on) it's reusable for quite a while.

@Ve2mrx

Ve2mrx commented Nov 16, 2026 •

Copy link
Copy Markdown

@Avamander No, I didn’t, and I couldn’t find one to try. Quectel’s L76K GNSS Protocol Specification (V1.1) documents only the standard NMEA sentences, PCAS01–PCAS04 and PCAS10, and the CASIC ACK, CFG-PRT, CFG-MSG, CFG-RST and CFG-RATE messages. Nothing reports whether the time is valid or the leap seconds are known. So the firmware relies on what NMEA gives: RMC status A, a 3D fix (#3821) and the settle before the sync (#3845). If you know of an undocumented CASIC message for it, send me the exact command and what to look for in the reply, and I can try it in a short test. This repeater is my only unit and has to stay on repeater duty, so short tests only.

On the almanac, this board already keeps it. The RAK12501 feeds the L76K’s V_BCKP from the always-on 3V3 (R25, 0 Ω); only VCC is on the switched GPS rail. So between daily windows the backup domain keeps the RTC, the almanac, the last position and the old ephemerides. That also is what gives the 3 s to 9 s hot starts after a reboot.

So the daily fix of about 30 s is the ephemeris download, not the satellite search. It matches the 30 s cold start in the L76K Hardware Design (V1.0), which gives no warm-start figure. Collecting a full almanac on purpose would take about 12.5 min at 29 mA, about 6.3 mAh. Even if it saved 5 s a day (about 0.04 mAh), it would take about five months to pay back.

My understanding is that almanacs mattered most for the early GPS receivers that had few channels and searched for satellites one at a time, which made each search slow. Today’s multichannel GNSS receivers search many satellites in parallel (the L76K reportedly has 32 tracking and 72 acquisition channels), so they find satellites quickly without needing an almanac. The almanac only helps find a satellite; the position is computed from that satellite’s ephemeris, which the receiver must then download. That download is the 30 s above, so an almanac doesn’t help much.

Who did what: I worked on this with Claude Code. Claude read the Quectel documents and the RAK12501 schematic, did the numbers and drafted this reply, which I reviewed before posting.

@Avamander

Copy link
Copy Markdown
Contributor

@Ve2mrx You should be looking at CASIC_Multimode_GNSS_Protocol_V4.2.0.3.pdf §2.7.5 NAV-TIMEUTC
image

I would presume that Reliable dates from multiple satellites would be the minimum people want if they're enabling other workarounds (to the receiver having no dedicated anti-spoof itself).

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

9 participants