Skip to content
  • Date Created: 2025-12-06
  • Last Modified: 2025-12-06

Progress Log: GNSS Debug Output - Remove Fix Guard

Task Description

The GNSS module was implemented with a conditional guard in stream_formatter.cpp that only output GNSS data (latitude, longitude, altitude, satellite count, fix quality, HDOP) when gnss_fix_valid was true. This meant that when the receiver was still acquiring satellites (common during initialization), no GNSS fields appeared in the output at all.

For debugging purposes, we needed to:

  1. Remove the gnss_fix_valid conditional guard in send_sv() function
  2. Always output all GNSS fields, regardless of fix validity
  3. Include the gnss_fix_valid flag (0 or 1) as the final GNSS field to indicate receiver status

This allows developers to see that GNSS data is being processed even when no valid fix has been acquired yet, which is essential for troubleshooting receiver initialization, UART communication, and NMEA parsing.

Outcome

Successfully modified src/stream_formatter.cpp in the send_sv() function (lines 103-119) to:

  • Remove the if (data->gnss_fix_valid) guard that was preventing output
  • Always output all GNSS fields in sequence: latitude, longitude, altitude, satellites, fix_quality, hdop, gnss_fix_valid
  • Added gnss_fix_valid as the final GNSS field (outputs 1 when fix acquired, 0 when searching)

Test Result:

100 100 100 1734... [lat=0.000000 lon=0.000000 alt=0.000000 sat=0 quality=0 hdop=0.0 valid=0]

The SSV output now shows 20 columns:

  1. hit1, hit2, hit3 (detection channels)
  2. adc (analog-to-digital value)
  3. temp, pressure, humidity (BME280 environmental data)
  4. uptime_ms (milliseconds since boot)
  5. timedelta_us (microseconds since last detection)
  6. latitude (GNSS decimal degrees)
  7. longitude (GNSS decimal degrees)
  8. altitude (GNSS meters above sea level)
  9. satellites (GNSS satellite count in use)
  10. fix_quality (GNSS fix quality indicator)
  11. hdop (GNSS horizontal dilution of precision)
  12. gnss_fix_valid (0 = searching, 1 = fixed)

With gnss_fix_valid=0 in the output, it's clear the receiver is still acquiring satellites - this is expected on cold start and confirms the module is operational.

Learnings

  1. Debugging vs Production: Conditional guards that hide data when conditions aren't met can mask initialization issues. For development/debugging, it's better to always output status flags so developers can see what's happening.

  2. Status Flag Design: Including a validity/status flag (gnss_fix_valid) in the output is more useful than silently omitting data, because:

  3. Developers can see the module is working but waiting for fix
  4. Field count remains consistent (easier for data parsing)

  5. Downstream tools can differentiate between "no data yet" (valid=0) vs "data not collected" (missing fields)

  6. Receiver Initialization Timeline: GT502MGG GNSS receivers typically take:

  7. First 30-60 seconds: Searching (cold start)
  8. 5-10 seconds: Hot start if almanac is cached
  9. The gnss_fix_valid flag changing from 0→1 confirms the module transitioned from SEARCHING to FIXED state

Next Steps

  1. Once receiver initialization is verified working and satellite acquisition is confirmed (gnss_fix_valid=1), consider making the output guard configurable via a build flag (e.g., -DENABLE_GNSS_DEBUG_OUTPUT=1) to allow switching between debug and production modes
  2. Monitor the gnss_fix_valid flag transitions during field deployment to verify the state machine is working correctly
  3. Document typical GNSS initialization timing in the user guide