microReticulumTbeam/exercises/10_Simple_GPS/README.md

Exercise 10: Simple GPS (No SD)

Goal: verify GPS satellite and UTC time acquisition on T-Beam Supreme using OLED-only status updates.

Current behavior

1. Boots PMU, OLED, RTC, and GPS UART.
2. Runs an active startup GPS probe (multi-baud + query commands) to detect GPS serial traffic.
3. Every 30 seconds:
   • Shows Trying to locate satellites + NMEA seen: yes/no + current RTC time.
   • Continues parsing GPS NMEA data.
   • If GPS UTC is valid, shows GPS UTC + satellite count + NMEA seen: yes/no.
   • Otherwise shows Take me outside + NMEA seen: yes/no + RTC.
4. No SD card logic is used in this exercise.

Walk-through: original approach and why

Initial implementation used a minimal/simple GPS strategy:

1. Power up PMU rails using the existing T-Beam adapter.
2. Start Serial1 at 9600 baud.
3. Parse incoming NMEA (GGA/GSV/RMC) passively.
4. Show periodic OLED status every 30 seconds.

Why this was chosen:

• It is the smallest path to validate basic GPS lock/time behavior.
• It avoids introducing SD complexity while isolating GPS.
• It is easy for field testing (OLED-first, battery-powered).

What was discovered by comparing with Meshtastic

Meshtastic GPS handling is more defensive and hardware-aware in principle:

1. It uses a board variant that provides explicit GPS pin mapping for the T-Beam Supreme path.
2. It initializes GPS serial with explicit RX/TX pins and larger receive buffers.
3. It performs active startup probing (commands + response checks), not only passive listening.
4. It attempts detection across known module families and may try multiple serial settings.
5. It manages GNSS-related power/standby states deliberately (rather than assuming default UART traffic immediately appears).

What differed in this exercise and likely caused the issue

The first Exercise 10 version was built on esp32-s3-devkitc-1 with conditional pin usage.

• If GPS pin macros are not present, Serial1 can start on default pins.
• That can produce NMEA seen: no forever even outdoors, because firmware is listening on the wrong UART pins.

Corrections applied after Meshtastic review

1. Added explicit GPS pin defines in platformio.ini:
   • GPS_RX_PIN=9
   • GPS_TX_PIN=8
   • GPS_WAKEUP_PIN=7
   • GPS_1PPS_PIN=6
2. Forced UART startup using explicit RX/TX pins.
3. Added startup multi-baud active probe and common GPS query commands.
4. Added OLED NMEA seen: yes/no so field tests distinguish:
   • no sky fix yet vs
   • no GPS serial traffic at all.

Field Test Checklist

1. Flash and reboot outdoors with clear sky view.
2. Confirm the OLED updates every 30 seconds.
3. Watch for this expected progression:
   • Trying to locate satellites + NMEA seen: no
   • then Trying to locate satellites + NMEA seen: yes
   • then either:
     • GPS lock acquired with UTC and satellite count, or
     • Take me outside if no fix yet.
4. Keep unit stationary for 2-5 minutes for first lock after cold start.

Interpretation guide:

• NMEA seen: no: likely UART/pin/baud/module-power communication issue.
• NMEA seen: yes + no lock: GPS is talking, but no valid fix yet (sky view/time-to-first-fix issue).
• GPS lock acquired: fix is valid; UTC and satellites are available from GPS.
• RTC line updates every 30 seconds: loop is alive and retry cycle is running.

If still failing:

1. Capture serial log from boot through at least 2 full 30-second cycles.
2. Note whether NMEA seen ever changes from no to yes.
3. Record whether GPS startup probe reports traffic at any baud rate.

Build

source /home/jlpoole/rnsenv/bin/activate
pio run -e node_a

Upload

source /home/jlpoole/rnsenv/bin/activate
pio run -e node_a -t upload --upload-port /dev/ttyACM0