From 9c30d4798294fb719068a7c7e3d139ae53238e48 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Cl=C3=A9ment=20Martin?= Date: Sun, 4 Oct 2026 22:00:09 +0200 Subject: [PATCH] M2 design: GNSS plan, glossary (GNSS Service, Fix, Track), ADR 0001 note Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01EhqxQ49eCju4CzKYNjZzwT --- CONTEXT.md | 12 ++++++ .../0001-own-firmware-speaking-meshtastic.md | 4 ++ docs/milestones/M2.md | 40 +++++++++++++++++++ 3 files changed, 56 insertions(+) create mode 100644 docs/milestones/M2.md diff --git a/CONTEXT.md b/CONTEXT.md index 453e93b..8318b4c 100644 --- a/CONTEXT.md +++ b/CONTEXT.md @@ -40,6 +40,18 @@ _Avoid_: DM (in docs), private message Rebroadcasting another Node's packet so it travels further across the mesh. _Avoid_: forwarding, repeating +**GNSS Service**: +The Service that owns the GNSS receiver on the Cap: it reads its NMEA sentences in the background and holds the current Fix, position, time and satellites. +_Avoid_: GPS (GPS is one constellation among several) + +**Fix**: +What the receiver currently knows: none, 2D (position without altitude) or 3D (with altitude), from how many satellites, at what HDOP. +_Avoid_: lock, signal + +**Track**: +A route recorded from GNSS positions to a GPX file on the SD card, started and stopped by the user. +_Avoid_: trace, log (a Log is recorded on its own) + **Wi-Fi Service**: The Service that owns the Wi-Fi radio. It's always in exactly one mode: *Off*, *Connected* (joined to a Saved Network) or *Monitoring* (passively observing). When Wi-Fi is enabled in Settings, it stays Connected whenever a Saved Network is in range. It goes Monitoring only while Wi-Fi Tools needs it, then reconnects. _Avoid_: network manager diff --git a/docs/adr/0001-own-firmware-speaking-meshtastic.md b/docs/adr/0001-own-firmware-speaking-meshtastic.md index fb600c0..baa3dc2 100644 --- a/docs/adr/0001-own-firmware-speaking-meshtastic.md +++ b/docs/adr/0001-own-firmware-speaking-meshtastic.md @@ -9,3 +9,7 @@ A fork would give full compatibility on day one, but its architecture is built a - We accept partial Meshtastic compatibility at first: text on channels, Direct Messages, node list, position and relaying. - The phone-app (BLE) API and PKI-encrypted Direct Messages are deferred, and we must re-implement protocol details ourselves. - Multi-boot with stock Meshtastic via a launcher was rejected: it gives none of our own UX. + +## Note (2026-10-04, M2) + +NMEA is parsed by our own small, host-tested parser instead of TinyGPSPlus: the GNSS App's Sky view needs the satellite list (GSV) across several constellations, which TinyGPSPlus doesn't track. See docs/milestones/M2.md, Q66. diff --git a/docs/milestones/M2.md b/docs/milestones/M2.md new file mode 100644 index 0000000..6a07a08 --- /dev/null +++ b/docs/milestones/M2.md @@ -0,0 +1,40 @@ +# M2 — GNSS + +**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. Meshtastic's board file for this hardware uses GPIO 15 (ESP32 RX) and 13 (TX); M5Stack's page names GPIO 8 and 9, which the keyboard controller already uses. Step 1 checks on the device. + +## Decisions (design round 2026-10-04) + +| # | Decision | +|---|---| +| Q58 | Settings has a GNSS On/Off switch, **On by default**. Off puts the receiver in standby if it accepts a command for it (measured in step 1); otherwise the firmware stops listening. | +| 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 when NTP hasn't this boot**. NTP stays preferred when online. | +| Q63 | A **Track** is started and stopped in the GNSS App. It's written as GPX to `/gnss/tracks/.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. | + +## 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.