roro9stack/docs/milestones/M2.md

# M2 — GNSS

**Status:** done on the device (branch `m2`): every "Done when" item below is met.

## Measured

- **Cold start** (`$PCAS10,2`) to a 3D Fix, by a window: **73 s**, 5 satellites used of 8 in view. A restart of the ESP32 alone keeps the receiver's Fix (the Cap stays powered).
- By a window: 3D Fix from GPS, GLONASS, Galileo and BeiDou, up to 14 of 17 satellites used, HDOP 1.0–1.3.
- **Heap, Debug Build, GNSS on, IRC on TLS** (floor 40 KB; v0.2.1 had a 79 KB low):

  | | Free | Lowest |
  |---|---|---|
  | Start of M2 | 31 KB | 12.6 KB |
  | Stacks and buffers trimmed by measurement | 46 KB | 18 KB |
  | mDNS removed | 54 KB | 34 KB |
  | Framework rebuilt with smaller TLS buffers (ADR 0006) | **78 KB** | **59 KB** |

  Under the heaviest combined load measured (IRC, two refused installs, a 1.6 MB put and get), the low is 46 KB. The cost had come mostly from the OTA and Debug Build work, not GNSS. Stacks were set to measured peak plus about 2 KB (loop 6 KB, update 5, storage 6, irc 6); after a TLS handshake the irc task has 1.7 KB left. IRC can now be stopped by hand (`/quit` in any state, `irc stop`), which frees its TLS memory.

**Goal:** the device knows where it is and what time it is without a network: a GNSS Service in the background, a GNSS App with the position and a sky view of the satellites, the clock set from satellites when there's no NTP, and Tracks recorded to the SD card.

**Hardware:** the Cap LoRa-1262 carries an ATGM336H-6N (AT6668), multi-constellation (GPS, BeiDou, Galileo, GLONASS, QZSS), with a ceramic antenna. NMEA over UART, 115200 8N1. **Measured (step 1, `gnss probe`): RX GPIO 15, TX GPIO 13, 115200 8N1**, as in Meshtastic's board file; M5Stack's page names GPIO 8 and 9, which are the internal I2C bus the keyboard controller sits on. Output is NMEA 4.10 style: `GN` RMC, VTG and GGA, one GSA per constellation with the system ID (1 GPS, 2 GLONASS, 3 Galileo, 4 BeiDou, 5 QZSS) in its last field, and a GSV sequence per constellation and signal (`GP`, `GL`, `GA`, …) with the signal ID last. RMC carries a time even without a Fix (status `V`), so only a Fix makes it trustworthy.

## Decisions (design round 2026-10-04)

| # | Decision |
|---|---|
| Q58 | Settings has a GNSS On/Off switch, **On by default**. Off puts the receiver in standby. *Measured:* `$PCAS12,<seconds>` (CASIC) stops its output within a second, for up to at least 65535 s, and any command wakes it within a second; Off sends `PCAS12,65535` (renewed hourly), On sends a hot start, `PCAS10,0`. |
| Q59 | The **GNSS App** has two views, switched with Tab. *Position*: latitude, longitude, altitude, speed, course, Fix (none / 2D / 3D), satellites used and in view, HDOP, UTC time. *Sky*: the satellites placed by azimuth and elevation, coloured by constellation, filled when used in the Fix. |
| Q60 | "Radar" in M2 means the Sky view. A radar of other Nodes by distance and bearing needs the mesh: M4. |
| Q61 | The **Status Bar** shows a GNSS mark: absent when off, muted while searching, normal with a 2D Fix, with the satellite count with a 3D Fix. |
| Q62 | GNSS time **sets the clock once there's a Fix**, and refreshes it every 10 minutes. *Revised in step 3:* the clock's trust order from M0 (Mesh < NTP < GNSS) already ranks GNSS above NTP, which is right: GNSS time is at least as accurate. So GNSS also corrects a clock NTP set, not only an unset one. |
| Q63 | A **Track** is started and stopped in the GNSS App. It's written as GPX to `/gnss/tracks/<YYYYMMDD-HHMMSS>.gpx`, a point every 5 s when the position moved more than 5 m. It keeps recording with the App closed, with a Toast on start and stop and a Status Bar mark, and gets its own Storage Clean-up category. |
| Q64 | Coordinates in **decimal degrees plus the Maidenhead locator**; a Settings switch for degrees, minutes and seconds. Metric units only. |
| Q65 | **The position never leaves the device in M2.** Sharing it over the mesh, and at what precision, is decided in M4. |
| Q66 | **Our own NMEA parser**, host-tested: RMC, GGA, GSA and GSV, with each talker ID mapped to its constellation. TinyGPSPlus (named in ADR 0001) doesn't track the satellite list across constellations, which the Sky view needs. |
| Q67 | The receiver keeps its **defaults** (all constellations, 1 Hz). No receiver settings. Time to first fix is measured and recorded here. |
| Q68 | Debug aids: `gnss status`, and `gnss nmea on/off` to stream the raw sentences to the console (USB serial and Debug Console). Raw NMEA is never written to the card. |

**Lesson (step 3):** the first probe also tried the pins swapped, driving the receiver's output line from the ESP32 for about a second. The receiver then went silent until a full power cycle (an ESP32 restart doesn't cut the Cap's power). Never drive GPIO 15.

## Done when

- The GNSS Service reads NMEA in the background whatever App is on screen, and a 3D Fix appears outdoors.
- The GNSS App shows the Position and Sky views, both live.
- The Status Bar shows the GNSS mark per Q61.
- With no Wi-Fi, the clock is set from GNSS after the first Fix.
- A Track records while the App is closed, survives the screen turning off, and opens as valid GPX on the PC.
- Settings → GNSS Off stops it (and the Status Bar mark goes away); On brings it back.
- Free heap stays above about 40 KB with GNSS, Wi-Fi, IRC on TLS and the UI running.

## Work breakdown

1. **Hardware check:** a `gnss probe` command reads the candidate UART pins and reports which carries NMEA, at what baud rate, and which talker IDs. Then the standby command (Q58) and a first time to first fix.
2. **NMEA parser** (host-tested): checksum, RMC, GGA, GSA, GSV across constellations, merged into one GNSS state (Fix, position, time, satellites).
3. **GNSS Service:** UART on its own task, the parser, `gnss status` and `gnss nmea`, Settings On/Off.
4. **Clock from GNSS** (Q62), and the Status Bar mark (Q61).
5. **GNSS App:** Position view, Maidenhead and coordinate formats (host-tested), then the Sky view.
6. **Tracks:** the 5 s / 5 m rule and GPX writing (host-tested), background recording, Clean-up category.